@osovv/vv-opencode 0.9.1 → 0.11.0

package/README.md

@@ -1,221 +1,278 @@
 # @osovv/vv-opencode
 
-Portable OpenCode workflow package with plugins and a Bun CLI for install, sync, and cross-device setup.
+Portable OpenCode workflow package with plugins and a Bun CLI for setup, sync, diagnostics, and explicit memory.
 
-Current package scope:
+## What You Get
 
+- `vvoc` CLI for bootstrap, sync, inspection, and model overrides
 - `GuardianPlugin` for permission review
 - `MemoryPlugin` for explicit persistent memory
-- built-in `memory-reviewer` subagent for report-only memory audits
-- vvoc-managed subagents: `implementer`, `spec-reviewer`, `code-reviewer`, `investitagor`
-- `vvoc` CLI for bootstrap, sync, and diagnostics
-- vvoc-managed config kept separate from OpenCode config
-
-## What is included
-
-- npm package: `@osovv/vv-opencode`
-- binary: `vvoc`
-- exported plugins:
-  - `GuardianPlugin`
-  - `MemoryPlugin`
-- CLI commands:
-  - `agent`
-  - `completion`
-  - `config`
-  - `init`
-  - `install`
-  - `path-provider`
-  - `plugin`
-  - `sync`
-  - `status`
-  - `doctor`
-  - `guardian`
-  - `upgrade`
-  - `version`
-
-## Installation
-
-Install into the current project:
+- `SecretsRedactionPlugin` for redacting secrets before LLM requests
+- report-only `memory-reviewer` subagent
+- vvoc-managed prompt files and OpenCode agent registrations
+- managed primary agent `enhancer` for meta-prompting raw intent into structured XML
+
+## Quick Start
+
+Examples below use `vvoc` directly.
+
+Install the package:
 
 ```bash
-bun add @osovv/vv-opencode
+bun add -g @osovv/vv-opencode
 ```
 
-Use the CLI as:
+Bootstrap the default global setup:
 
 ```bash
-vvoc --help
+vvoc install
 ```
 
-Examples below use `vvoc` directly and assume the binary is available in your `PATH`.
+Inspect the result:
 
-## OpenCode usage
+```bash
+vvoc status
+```
 
-Add the package to your OpenCode config with a pinned version:
+Use project-local scope instead of global scope:
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@osovv/vv-opencode@<installed-version>"]
-}
+```bash
+vvoc install --scope project
 ```
 
-OpenCode loads all exported plugin functions from the package, so this enables both `GuardianPlugin` and `MemoryPlugin`.
-
-`vvoc install` writes this pinned package specifier automatically and avoids stale `latest` plugin cache behavior inside OpenCode.
+`vvoc install` does the following:
 
-## Config layout
+- adds a pinned `@osovv/vv-opencode@<installed-version>` entry to the OpenCode `plugin` array
+- registers vvoc-managed OpenCode agents, including the primary `enhancer` agent
+- creates managed prompt files under `vvoc/agents/` when missing
+- creates `guardian.jsonc`, `memory.jsonc`, and `secrets-redaction.config.json` when missing
+- keeps vvoc-managed config separate from native OpenCode config
+- leaves unmanaged files alone unless `--force` is passed
 
-OpenCode config stays in OpenCode-managed locations:
+For conversational meta-prompting, use the managed `enhancer` primary agent. It can ask follow-up questions and then return a clean XML prompt with semantically unique repeated tags such as `<constraint-1>...</constraint-1>` and `<verification-check-2>...</verification-check-2>`.
 
-- global: `$XDG_CONFIG_HOME/opencode/opencode.json` or `~/.config/opencode/opencode.json`
-- project: `./opencode.json` or `./opencode.jsonc`
+Typical workflow:
 
-vvoc-managed config stays separate:
-
-- global: `$XDG_CONFIG_HOME/vvoc/` or `~/.config/vvoc/`
-- project: `./.vvoc/`
-
-vvoc persisted data stays in the XDG data root:
+```text
+1. Start a fresh session with the enhancer agent
+2. Paste the rough request in plain language
+3. Answer any short follow-up questions
+4. Copy the final XML prompt into the execution session
+```
 
-- global data: `$XDG_DATA_HOME/vvoc/` or `~/.local/share/vvoc/`
+The OpenCode config entry written by `install` looks like this:
 
-Examples:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@osovv/vv-opencode@<installed-version>"]
+}
+```
 
-- global Guardian config: `~/.config/vvoc/guardian.jsonc`
-- project Guardian config: `./.vvoc/guardian.jsonc`
-- project-local memory data: `~/.local/share/vvoc/projects/<project-id>/memory/`
-- global shared memory data: `~/.local/share/vvoc/memory/shared/<namespace>/`
-- project memory settings: `./.vvoc/memory.jsonc`
-- global managed agent prompts: `~/.config/vvoc/agents/*.md`
-- project managed agent prompts: `./.vvoc/agents/*.md`
+That package entry points at the package root, which exports `GuardianPlugin`, `MemoryPlugin`, and `SecretsRedactionPlugin`.
 
-This keeps vvoc state clearly separated from native OpenCode config and avoids future clashes if OpenCode adds its own memory features.
+## Common Workflows
 
-## CLI
+### Interactive Bootstrap
 
-Show help:
+Use `init` when you want an interactive setup flow:
 
 ```bash
-vvoc --help
+vvoc init
+vvoc init --scope project
 ```
 
-Show the installed `vvoc` package version:
+Use `--non-interactive` if you want `init` without prompts:
 
 ```bash
-vvoc version
+vvoc init --non-interactive --scope project
 ```
 
-Install package config and bootstrap Guardian + Memory config plus managed subagents:
+### Scripted Install
+
+`install` is the non-interactive bootstrap command and is the best fit for repeatable setup:
 
 ```bash
 vvoc install
+vvoc install --scope project
+vvoc install --config-dir /tmp/vvoc-home
 ```
 
-`install` writes the current installed package version into the OpenCode `plugin` array instead of using an unpinned `latest` reference.
-It also registers vvoc-managed subagents in OpenCode config and creates managed `guardian.jsonc`, `memory.jsonc`, and `vvoc/agents/*.md` prompt files when they are missing.
+When `--config-dir` is used for global scope, `vvoc` writes under the supplied root for both `opencode/` and `vvoc/`.
+
+### Sync Managed Files
 
-Use project scope instead of global scope:
+Refresh the pinned package entry, managed agent registrations, managed prompt files, and managed `guardian.jsonc` / `memory.jsonc` files:
 
 ```bash
-vvoc install --scope project
+vvoc sync
+vvoc sync --scope project
 ```
 
-Override the global config home used for both `opencode/` and `vvoc/`:
+### Inspect And Validate Setup
 
 ```bash
-vvoc install --config-dir /tmp/vvoc-home
+vvoc status
+vvoc doctor
+vvoc config validate
 ```
 
-This writes:
-
-- `/tmp/vvoc-home/opencode/opencode.json`
-- `/tmp/vvoc-home/vvoc/guardian.jsonc`
-- `/tmp/vvoc-home/vvoc/memory.jsonc`
-- `/tmp/vvoc-home/vvoc/agents/guardian.md`
-- `/tmp/vvoc-home/vvoc/agents/memory-reviewer.md`
-- `/tmp/vvoc-home/vvoc/agents/implementer.md`
-- `/tmp/vvoc-home/vvoc/agents/spec-reviewer.md`
-- `/tmp/vvoc-home/vvoc/agents/code-reviewer.md`
-- `/tmp/vvoc-home/vvoc/agents/investitagor.md`
+- `status` shows the current installation state
+- `doctor` reports parse problems and missing required setup
+- `config validate` validates `guardian.jsonc` and `memory.jsonc` in global, project, or both scopes
 
-Sync managed config files:
+Validate a specific scope or config type:
 
 ```bash
-vvoc sync
+vvoc config validate --scope global
+vvoc config validate --scope project --guardian-only
+vvoc config validate --scope project --memory-only
 ```
 
-Patch the global OpenCode StepFun provider to use the `stepfun.ai` endpoint:
+### Manage Agent Models
+
+List configured model overrides:
 
 ```bash
-vvoc path-provider stepfun-ai
+vvoc agent list
 ```
 
-This writes `provider.stepfun.options.baseURL = "https://api.stepfun.ai/v1"` into the global OpenCode config.
-It does not manage auth for you, so keep using OpenCode's normal StepFun credential flow.
-
-Manage model overrides for built-in and bundled agents:
+Set model overrides:
 
 ```bash
-vvoc agent list
 vvoc agent set general openai/gpt-5-nano
 vvoc agent set explore openai/gpt-5-nano
+vvoc agent set enhancer openai/gpt-5
 vvoc agent set implementer openai/gpt-5
 vvoc agent set code-reviewer anthropic/claude-sonnet-4-20250514
-vvoc agent unset spec-reviewer
+vvoc agent set guardian anthropic/claude-sonnet-4-5:high
+vvoc agent set memory-reviewer openai/gpt-5:high
 ```
 
-`vvoc agent set general ...` and `vvoc agent set explore ...` write `agent.general.model` and `agent.explore.model` into OpenCode config so the built-in subagents do not inherit the main session model.
-
-Inspect current setup:
+Remove overrides:
 
 ```bash
-vvoc status
-vvoc doctor
+vvoc agent unset spec-reviewer
+vvoc agent unset guardian
+vvoc agent unset memory-reviewer
 ```
 
-Install shell completions for the current shell:
+Supported agent IDs:
+
+- `guardian`
+- `memory-reviewer`
+- `general`
+- `explore`
+- `enhancer`
+- `implementer`
+- `spec-reviewer`
+- `code-reviewer`
+- `investitagor`
+
+`guardian` and `memory-reviewer` accept `provider/model[:variant]` syntax. The other agent targets use `provider/model`.
+
+### Plugin Inspection, Provider Presets, And Shell Completion
 
 ```bash
+vvoc plugin list
+vvoc plugin list --verbose
+vvoc path-provider stepfun-ai
 vvoc completion
 ```
 
-For `zsh`, `vvoc completion` writes `~/.zsh/completions/_vvoc` and appends a small loader block to `~/.zshrc`.
+- `plugin list` shows plugin entries from OpenCode config
+- `path-provider stepfun-ai` patches the global OpenCode provider base URL for StepFun
+- `completion` installs completions for the current shell (`bash`, `zsh`, or `fish`)
 
-Generate or print `guardian.jsonc`:
+### Check For Upgrades
 
 ```bash
-vvoc guardian config --print
-vvoc guardian config --model "anthropic/claude-sonnet-4-5" --variant high
+vvoc upgrade
+vvoc version
 ```
 
-### Guardian config behavior
+## Command Reference
 
-`vvoc` creates a managed `guardian.jsonc` with a marker header.
+| Command | Purpose |
+| --- | --- |
+| `vvoc init` | Interactive bootstrap flow |
+| `vvoc install` | Non-interactive setup and scaffolding |
+| `vvoc sync` | Refresh managed config and prompt files |
+| `vvoc status` | Show current installation state |
+| `vvoc doctor` | Diagnose setup problems |
+| `vvoc agent list/set/unset` | Manage model overrides |
+| `vvoc guardian config` | Print or write `guardian.jsonc` |
+| `vvoc config validate` | Validate `guardian.jsonc` and `memory.jsonc` |
+| `vvoc plugin list` | List OpenCode plugins from config |
+| `vvoc path-provider stepfun-ai` | Patch a global provider endpoint preset |
+| `vvoc completion` | Install shell completions |
+| `vvoc upgrade` | Check npm for a newer package version |
+| `vvoc version` | Print the installed `vvoc` version |
 
-- managed files can be resynced safely
-- existing unmanaged files are not overwritten unless `--force` is passed
-- Guardian now reads vvoc-managed config from `.vvoc/` or `$XDG_CONFIG_HOME/vvoc/`
-- `vvoc install` also creates `memory.jsonc` when it is missing
+## Config And Data Layout
 
-### Memory config behavior
+OpenCode config stays in OpenCode-managed paths:
 
-`vvoc` also manages `memory.jsonc`.
+- global: `$XDG_CONFIG_HOME/opencode/opencode.json` or `~/.config/opencode/opencode.json`
+- project: `./opencode.json` or `./opencode.jsonc`
 
-Current supported settings:
+vvoc-managed config stays separate:
 
-```jsonc
-{
-  "enabled": true,
-  "defaultSearchLimit": 8
-}
+- global: `$XDG_CONFIG_HOME/vvoc/` or `~/.config/vvoc/`
+- project: `./.vvoc/`
+
+Persisted vvoc data lives under the XDG data root:
+
+- global data root: `$XDG_DATA_HOME/vvoc/` or `~/.local/share/vvoc/`
+- project-local memory: `$XDG_DATA_HOME/vvoc/projects/<project-id>/memory/`
+- shared memory: `$XDG_DATA_HOME/vvoc/memory/shared/<namespace>/`
+
+Managed prompt files live here:
+
+- global: `~/.config/vvoc/agents/*.md`
+- project: `./.vvoc/agents/*.md`
+
+Common managed config files:
+
+- global Guardian config: `~/.config/vvoc/guardian.jsonc`
+- project Guardian config: `./.vvoc/guardian.jsonc`
+- global Memory config: `~/.config/vvoc/memory.jsonc`
+- project Memory config: `./.vvoc/memory.jsonc`
+- global Secrets Redaction config: `~/.config/vvoc/secrets-redaction.config.json`
+- project Secrets Redaction config: `./.vvoc/secrets-redaction.config.json`
+
+Scope rules:
+
+- project config overrides global config for vvoc-managed settings
+- managed files include a marker header so `vvoc` can recognize them safely
+- existing unmanaged files are not rewritten unless `--force` is passed
+
+## Plugins Included
+
+### GuardianPlugin
+
+`GuardianPlugin` reviews OpenCode permission requests with a constrained Guardian agent and safe deny behavior.
+
+Generate or rewrite a managed `guardian.jsonc` file:
+
+```bash
+vvoc guardian config --print
+vvoc guardian config --model "anthropic/claude-sonnet-4-5" --variant high
 ```
 
-Project config overrides global config.
+Supported Guardian config fields:
+
+- `model`
+- `variant`
+- `timeoutMs`
+- `approvalRiskThreshold`
+- `reviewToastDurationMs`
 
-## Memory plugin
+`guardian.jsonc` is only auto-rewritten when it is clearly vvoc-managed, unless you pass `--force`.
 
-`MemoryPlugin` adds explicit memory tools to OpenCode.
+### MemoryPlugin
+
+`MemoryPlugin` adds explicit persistent memory tools to OpenCode.
 
 Available tools:
 
@@ -229,78 +286,94 @@ Available tools:
 Memory is explicit-only:
 
 - stored entries are never injected into the prompt automatically
-- the agent must call memory tools directly when it needs durable context
-- memory settings live in `./.vvoc/memory.jsonc` or `$XDG_CONFIG_HOME/vvoc/memory.jsonc`
-- session, branch, and project memory data live under `$XDG_DATA_HOME/vvoc/projects/<project-id>/memory/`
-- shared memory data lives under `$XDG_DATA_HOME/vvoc/memory/shared/<namespace>/`
-- the plugin adds a short system instruction that reminds the agent to consider memory tools proactively when durable context may help
+- the agent must call memory tools directly when durable context is useful
+- settings live in `./.vvoc/memory.jsonc` or `$XDG_CONFIG_HOME/vvoc/memory.jsonc`
 
 Supported scopes:
 
-- `session` - local to the current session in the current project
-- `branch` - local to the current git branch in the current project
-- `project` - local to the current project
-- `shared` - global across projects
-
-In practice:
+- `session` for the current session in the current project
+- `branch` for the current git branch in the current project
+- `project` for repository-specific memory
+- `shared` for cross-project memory
 
-- use `shared` for reusable personal preferences, reusable docs locations, and cross-project habits
-- use `project` for repository-specific facts and workflows
-- use `branch` for work that only matters on one branch
-- use `session` for temporary context you want to keep only for the current session
+`memory.jsonc` supports these fields:
 
-### Memory review
+- `enabled`
+- `defaultSearchLimit`
+- `reviewerModel`
+- `reviewerVariant`
 
 The package also installs a bundled reviewer subagent named `memory-reviewer`.
 
-Use it when you want a report-only audit of stored memory:
+Example:
 
 ```text
 @memory-reviewer review the current memory and suggest keep/update/merge/delete actions
 ```
 
-The reviewer can read memory with `memory_list`, `memory_get`, and `memory_search`, but it does not modify entries.
+The reviewer can read memory but cannot modify it.
 
-## Managed agent prompts
+### SecretsRedactionPlugin
 
-`vvoc install` and `vvoc sync` create vvoc-managed prompt files under:
+`SecretsRedactionPlugin` redacts secrets from chat content before LLM requests and restores placeholders after the request lifecycle where needed.
 
-- global: `~/.config/vvoc/agents/*.md`
-- project: `./.vvoc/agents/*.md`
+`vvoc install` scaffolds a managed `secrets-redaction.config.json` file. The generated config uses:
 
-This includes:
+```json
+{
+  "secret": "${VVOC_SECRET}"
+}
+```
+
+Set `VVOC_SECRET` if you want placeholder restoration to stay stable across restarts.
+
+If no config file exists, the plugin falls back to defaults and generates a random secret for the current runtime.
+
+Built-in patterns cover common identifiers and tokens such as:
+
+- email addresses
+- UUIDs
+- IP and MAC addresses
+- OpenAI, Anthropic, GitHub, AWS, and Stripe-style keys
+- bearer tokens and generic hex-like tokens
 
-- `guardian.md`
-- `memory-reviewer.md`
-- `implementer.md`
-- `spec-reviewer.md`
-- `code-reviewer.md`
-- `investitagor.md`
+## Managed Prompts And Subagents
 
-`GuardianPlugin` and `MemoryPlugin` now read `guardian.md` and `memory-reviewer.md` from those vvoc-managed paths at runtime.
-There is no bundled runtime fallback, so missing files should be repaired with `vvoc install` or `vvoc sync`.
+`vvoc` manages prompt files for:
 
-## Managed subagents
+- `guardian`
+- `memory-reviewer`
+- `implementer`
+- `spec-reviewer`
+- `code-reviewer`
+- `investitagor`
 
-`vvoc install` and `vvoc sync` also register four OpenCode subagents in `opencode.json`:
+`install` and `sync` register these OpenCode subagents in `opencode.json`:
 
 - `implementer`
 - `spec-reviewer`
 - `code-reviewer`
 - `investitagor`
 
-Their prompt files also live under the same vvoc-managed `agents/` directory instead of being embedded directly into the TypeScript command code.
+`GuardianPlugin` and `MemoryPlugin` load `guardian.md` and `memory-reviewer.md` from vvoc-managed paths at runtime.
 
-OpenCode registration stays in `opencode.json`, but each agent points its `prompt` field at the vvoc-managed file with a relative `{file:...}` reference.
+If a managed prompt file is missing, rerun one of these commands:
 
-Model overrides for these four subagents, plus the built-in `general` and `explore` subagents, are written into the corresponding `agent.<name>.model` entry inside OpenCode config via `vvoc agent set|unset ...`.
+```bash
+vvoc install
+vvoc sync
+```
 
 ## Package API
 
 Root exports:
 
 ```ts
-import { GuardianPlugin, MemoryPlugin } from "@osovv/vv-opencode";
+import {
+  GuardianPlugin,
+  MemoryPlugin,
+  SecretsRedactionPlugin,
+} from "@osovv/vv-opencode";
 ```
 
 Subpath exports:
@@ -308,9 +381,10 @@ Subpath exports:
 ```ts
 import { GuardianPlugin } from "@osovv/vv-opencode/plugins/guardian";
 import { MemoryPlugin } from "@osovv/vv-opencode/plugins/memory";
+import { SecretsRedactionPlugin } from "@osovv/vv-opencode/plugins/secrets-redaction";
 ```
 
-## Local development
+## Local Development
 
 Install dependencies:
 
@@ -318,7 +392,7 @@ Install dependencies:
 bun install
 ```
 
-Run checks:
+Run the full local verification stack:
 
 ```bash
 bun run typecheck
@@ -326,6 +400,7 @@ bun run lint
 bun run fmt:check
 bun test
 bun run build
+bun run pack:check
 ```
 
 Format source files:
@@ -339,7 +414,7 @@ Git hooks are managed with `lefthook`.
 - `bun install` runs `lefthook install --force` through the `prepare` script
 - the `pre-commit` hook runs `bun run lint` and `bun run fmt:check`
 
-Smoke-test the CLI against a temporary config home:
+Smoke-test the built CLI against a temporary config root:
 
 ```bash
 tmpdir="$(mktemp -d)"
@@ -350,52 +425,20 @@ bun dist/cli.js status --config-dir "$tmpdir"
 
 ## Publishing
 
-This project is published manually from the terminal. There is no CI publish workflow.
+This package is published manually from the terminal.
 
 Typical release flow:
 
 ```bash
-bun run check
+bun run typecheck
+bun run lint
+bun run fmt:check
+bun test
 bun run build
 bun run pack:check
 npm publish
 ```
 
-## Repository layout
-
-- `src/plugins/guardian/` - Guardian OpenCode plugin runtime
-- `src/plugins/memory/` - Memory OpenCode plugin runtime + system instruction
-- `templates/agents/` - canonical managed prompt templates copied into `vvoc/agents/`
-- `src/plugins/memory-store.ts` - file-based memory store and search logic
-- `src/lib/opencode.ts` - config path resolution and JSONC helpers for the CLI
-- `src/lib/vvoc-paths.ts` - shared vvoc/openCode path helpers
-- `src/commands/` - `vvoc` commands
-- `src/cli.ts` - CLI entrypoint
-- `docs/` - GRACE planning, verification, and graph artifacts
-
-## Notes
-
-- `src/` is the source of truth
-- `dist/` is generated output for packaging and local smoke tests
-- if you change CLI behavior, plugin exports, vvoc config paths, or memory workflow, keep this README in sync
-
-## Highly Recommended Addons
-
-### RTK — LLM Token Optimizer
-
-[RTK](https://github.com/rtk-ai/rtk) is a CLI proxy that reduces LLM token consumption by 60-90% on common dev commands like `git`, `ls`, `cat`, `rg`, `grep`, `pytest`, `cargo test`, and 100+ more. Single Rust binary, zero dependencies.
-
-**Why use it with vvoc:**
-- Transparent command rewriting — no workflow changes needed
-- Works alongside vvoc's Guardian and Memory plugins
-- Minimal overhead (<10ms)
-
-**Quick install:**
-```bash
-curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
-rtk init -g --opencode
-```
-
-After install, commands like `git status` and `cargo test` are automatically rewritten to their RTK equivalents, producing compact output that costs 60-90% fewer tokens.
+## Optional: RTK
 
-For more commands and details, see the [RTK documentation](https://github.com/rtk-ai/rtk).
+[RTK](https://github.com/rtk-ai/rtk) is a CLI proxy that reduces token usage for common developer commands. It works well alongside `vvoc`, and the interactive `vvoc init` flow recommends it after setup.