vgxness 1.2.1 → 1.3.1

package/docs/funcionamiento-del-sistema.md

@@ -25,7 +25,7 @@ Para resolverlos, el sistema se construye sobre estos bloques:
 | Politica de permisos | Decide si una operacion se permite, se bloquea o requiere aprobacion humana. |
 | MCP server | Expone herramientas para que agentes consulten y actualicen el control plane. |
 | CLI | Permite operar el sistema desde comandos reproducibles. |
-| Dashboard/TUI | Muestra estado local, setup, runs y progreso SDD para humanos. |
+| TUI | Muestra setup y guias operativas locales para humanos. |
 
 ## Que problema resuelve
 
@@ -58,7 +58,7 @@ Scripts principales:
 
 | Script | Funcion |
 |---|---|
-| `npm run cli -- ...` | Ejecuta la CLI local desde `src/cli/index.ts`. |
+| `bun run cli:bun -- ...` | Ejecuta la CLI local desde el repo usando el mismo runtime Bun que los bins instalados. |
 | `npm run build` | Compila TypeScript y copia migraciones. |
 | `npm run test` | Ejecuta tests con el runner nativo de Node. |
 | `npm run typecheck` | Valida tipos sin emitir archivos. |
@@ -71,7 +71,7 @@ Humano / operador
       |
       | usa
       v
-CLI / Dashboard / TUI
+CLI / TUI
       |
       | llama servicios locales
       v
@@ -92,7 +92,7 @@ MCP control plane
 Core de vgxness
 ```
 
-La regla importante es que CLI, MCP y dashboard no deberian tener reglas de negocio duplicadas. Todos deben pasar por los mismos servicios de dominio.
+La regla importante es que CLI, MCP y TUI no deberian tener reglas de negocio duplicadas. Todos deben pasar por los mismos servicios de dominio.
 
 ## Capas del sistema
 
@@ -105,7 +105,7 @@ El sistema tiene varias superficies de uso.
 | CLI | Humano, scripts, smoke tests | `src/cli/dispatcher.ts` | Parsear comandos y llamar servicios. |
 | MCP stdio | Agentes y herramientas IA | `src/mcp/stdio-server.ts` | Exponer herramientas MCP locales. |
 | MCP control plane | Capa interna MCP | `src/mcp/control-plane.ts` | Validar tool calls y despacharlas a servicios. |
-| Dashboard/TUI | Humano local | `src/cli/interactive-dashboard.ts` | Mostrar estado operativo y permitir navegacion local. |
+| TUI | Humano local | `src/cli/tui/` | Mostrar setup y guias operativas locales. |
 
 La CLI es intencionalmente fina. Abre la base local, instancia servicios y devuelve JSON o texto. No deberia contener la logica profunda del producto.
 
@@ -170,10 +170,10 @@ Una accion puede entrar por CLI o por MCP.
 Ejemplos CLI:
 
 ```bash
-npm run cli -- sdd status --project vgxness --change my-change
-npm run cli -- orchestrator preview --project vgxness --intent "Build a new checkout workflow" --change checkout-flow
-npm run cli -- agents resolve --project vgxness --workflow sdd --phase apply-progress
-npm run cli -- runs list --project vgxness
+vgxness sdd status --project vgxness --change my-change
+vgxness orchestrator preview --project vgxness --intent "Build a new checkout workflow" --change checkout-flow
+vgxness agents resolve --project vgxness --workflow sdd --phase apply-progress
+vgxness runs list --project vgxness
 ```
 
 Ejemplo MCP:
@@ -305,7 +305,7 @@ Este seam es importante porque separa la decision de ruteo de la ejecucion real.
 La CLI expone el planner con:
 
 ```bash
-npm run cli -- orchestrator preview --project vgxness --intent "Build a new persistent checkout workflow" --change checkout-flow --db .vgx/memory.sqlite
+vgxness orchestrator preview --project vgxness --intent "Build a new persistent checkout workflow" --change checkout-flow --db .vgx/memory.sqlite
 ```
 
 Parametros:
@@ -325,7 +325,7 @@ Ejemplo de decision esperada:
 Intent: Build a new persistent checkout workflow capability
 Flow: sdd
 Suggested change id: checkout-flow
-Preview action: npm run cli -- sdd next --project vgxness --change checkout-flow
+Preview action: vgxness sdd next --project vgxness --change checkout-flow
 Safety: no ejecuto nada
 ```
 
@@ -416,7 +416,7 @@ La precedencia de seleccion de base es:
 La ruta historica `.vgx/memory.sqlite` sigue siendo compatible, pero ahora es explicita:
 
 ```bash
-npm run cli -- memory search --project vgxness --db .vgx/memory.sqlite
+vgxness memory search --project vgxness --db .vgx/memory.sqlite
 ```
 
 Este detalle es importante: `vgxness` puede funcionar como herramienta instalada globalmente sin acoplar la memoria al workdir actual, pero tambien permite aislar estado cuando se necesita reproducibilidad en tests o dogfood local.
@@ -616,7 +616,7 @@ Tools representativas (no exhaustivas; la fuente actual de nombres soportados es
 La CLI se ejecuta localmente con:
 
 ```bash
-npm run cli -- <area> <command> [flags]
+vgxness <area> <command> [flags]
 ```
 
 Areas principales vistas en el dispatcher:
@@ -633,7 +633,6 @@ Areas principales vistas en el dispatcher:
 | `sdd` | Estado, readiness y guardado de artefactos SDD. |
 | `orchestrator` | Preview de ruteo desde lenguaje natural hacia direct, plan, sdd o diagnose. |
 | `opencode` | Previews/integracion OpenCode. |
-| `dashboard` | Estado visual o interactivo. |
 | `mcp` | Setup, doctor e instalacion MCP. |
 
 La base se selecciona con la misma regla que el resto del sistema:
@@ -645,7 +644,7 @@ La base se selecciona con la misma regla que el resto del sistema:
 Sin `--db`, la CLI usa la base global de usuario. Si se quiere la base del repo para pruebas locales, se debe pedir explicitamente:
 
 ```bash
-npm run cli -- sdd status --project vgxness --change my-change --db .vgx/memory.sqlite
+vgxness sdd status --project vgxness --change my-change --db .vgx/memory.sqlite
 ```
 
 ## Setup local
@@ -693,7 +692,7 @@ El proyecto ya contiene implementaciones concretas de:
 7. Politica de permisos base.
 8. MCP stdio server y control plane.
 9. CLI para operar los servicios.
-10. Setup status y dashboard local.
+10. Setup status y TUI local.
 11. Integracion inicial con OpenCode.
 12. CLI instalable con memoria global por defecto y compatibilidad explicita con `--db`.
 
@@ -715,7 +714,7 @@ Supongamos que se quiere trabajar en un cambio llamado `add-agent-profiles`.
 ### 1. Revisar setup
 
 ```bash
-npm run cli -- setup status --project vgxness
+vgxness setup status --project vgxness
 ```
 
 El sistema revisa store, MCP y agente default.
@@ -723,7 +722,7 @@ El sistema revisa store, MCP y agente default.
 ### 2. Clasificar el pedido natural
 
 ```bash
-npm run cli -- orchestrator preview --project vgxness --intent "Build a new agent profile workflow" --change add-agent-profiles
+vgxness orchestrator preview --project vgxness --intent "Build a new agent profile workflow" --change add-agent-profiles
 ```
 
 El sistema devuelve un preview no ejecutable. Si detecta nueva capacidad, arquitectura, workflow, persistencia, seguridad o riesgo de ejecucion, recomienda `sdd` y puede incluir el proximo comando manual de SDD.
@@ -731,7 +730,7 @@ El sistema devuelve un preview no ejecutable. Si detecta nueva capacidad, arquit
 ### 3. Consultar estado SDD
 
 ```bash
-npm run cli -- sdd status --project vgxness --change add-agent-profiles
+vgxness sdd status --project vgxness --change add-agent-profiles
 ```
 
 Si no hay artefactos, la primera fase lista deberia ser `explore`.
@@ -739,7 +738,7 @@ Si no hay artefactos, la primera fase lista deberia ser `explore`.
 ### 4. Guardar el artefacto de exploracion
 
 ```bash
-npm run cli -- sdd save-artifact --project vgxness --change add-agent-profiles --phase explore --content "# Explore"
+vgxness sdd save-artifact --project vgxness --change add-agent-profiles --phase explore --content "# Explore"
 ```
 
 El sistema guarda el contenido en memoria como artefacto con topic key:
@@ -751,7 +750,7 @@ sdd/add-agent-profiles/explore
 ### 5. Preguntar la siguiente fase
 
 ```bash
-npm run cli -- sdd next --project vgxness --change add-agent-profiles
+vgxness sdd next --project vgxness --change add-agent-profiles
 ```
 
 Si `explore` esta presente, la siguiente fase runnable sera `proposal`.
@@ -759,7 +758,7 @@ Si `explore` esta presente, la siguiente fase runnable sera `proposal`.
 ### 6. Resolver un agente para implementar
 
 ```bash
-npm run cli -- agents resolve --project vgxness --workflow sdd --phase apply-progress --provider opencode --task "Implement agent profile routing"
+vgxness agents resolve --project vgxness --workflow sdd --phase apply-progress --provider opencode --task "Implement agent profile routing"
 ```
 
 El sistema devuelve candidatos con score y razones.
@@ -814,7 +813,7 @@ Si todo vive solo en prompts, el sistema depende de disciplina del LLM. Si todo
 ```text
 src/
   agents/        Registro, resolucion, activacion y renderers de agentes.
-  cli/           Dispatcher, dashboard y renderers de salida CLI.
+  cli/           Dispatcher, TUI y renderers de salida CLI.
   export/        Redaccion/export de snapshots.
   harness/       Handlers reutilizables para tools internas.
   mcp/           Servidor stdio, schemas, validacion, doctor e instalacion MCP.

package/docs/harness-gap-analysis.md

@@ -1,4 +1,18 @@
-# Harness Systems Gap Analysis
+# Historical Harness Systems Gap Analysis
+
+> **Status:** historical planning note. This document predates much of the v1 runtime foundation. Use `docs/architecture.md`, `docs/prd.md`, and `docs/cli.md` as the current product references. Keep this file for design context, not as a live gap checklist.
+
+## Current interpretation after v1.3.0
+
+Several items below now exist as v1 foundations: local run records, preflight/approval planning, SDD artifacts, memory-backed storage, agent/subagent registries, provider setup previews, package evidence, and MCP control-plane tools.
+
+The remaining strategic gaps are narrower:
+
+- real provider/executor dispatch instead of planning-only run execution;
+- stronger SDD governance gates that combine artifact presence, human acceptance, verification evidence, and blockers;
+- operational TUI screens for SDD, runs, approvals, doctor, and settings;
+- sandbox/worktree enforcement beyond advisory planning;
+- export/import/redaction and upgrade/rollback evidence for beta readiness.
 
 This research compares current agent harness patterns against the `vgxness` PRD and identifies what the product still needs before it can become a serious local-first SDD harness.
 

package/docs/prd.md

@@ -119,7 +119,7 @@ The MCP server is the main integration surface for AI coding tools. It should ex
 
 Minimum MCP capabilities:
 
-- Start a local MCP server through `vgx mcp start` or an installed provider config.
+- Start a local MCP server through `vgxness mcp start` or an installed provider config.
 - Install MCP integration for supported tools through guided setup.
 - Expose SDD status, readiness, next-phase, and artifact operations.
 - Expose run start/checkpoint/finalize and approval-request operations.
@@ -160,15 +160,15 @@ Minimum CLI capabilities:
 Candidate CLI shape:
 
 ```bash
-vgx init
-vgx doctor
-vgx status
-vgx mcp install opencode
-vgx mcp status
-vgx sdd status <change>
-vgx sdd next <change>
-vgx profiles list
-vgx profiles set apply <model>
+vgxness init
+vgxness doctor
+vgxness status
+vgxness mcp install opencode
+vgxness mcp status
+vgxness sdd status <change>
+vgxness sdd next <change>
+vgxness profiles list
+vgxness profiles set apply <model>
 ```
 
 #### TUI
@@ -190,7 +190,7 @@ TUI state requirements:
 
 - Loading, empty, error, success, blocked, and permission states must be explicit and actionable.
 - Keyboard navigation and visible focus are required.
-- The dashboard TUI is read-only; provider config writes/install/apply are external-only, require explicit confirmation outside the dashboard, and are not run by dashboard flows.
+- TUI status/setup surfaces are read-only; provider config writes/install/apply are external-only, require explicit confirmation outside the TUI, and are not run by preview/status flows.
 
 #### Installation experience
 
@@ -299,7 +299,7 @@ Minimum capabilities:
 - Cloud sync.
 - Multi-user collaboration.
 - Team permissions and governance.
-- Web dashboard.
+- Web console.
 - Hosted memory service.
 - Marketplace for agents.
 - Full provider parity across every AI coding tool.
@@ -332,11 +332,11 @@ After the MVP proves local individual usage, expand toward:
 - Team/shared memory spaces.
 - Permissions, governance, and audit trails.
 - PR and chained-PR coordination.
-- Hosted dashboard for inspection and collaboration.
+- Hosted web console for inspection and collaboration.
 - Additional provider adapters.
 - Import/export between local and cloud memory backends.
 - Distributed agent workers.
-- Hosted observability and evaluation dashboard.
+- Hosted observability and evaluation UI.
 - Skill marketplace or shared skill catalog.
 
 ## Success criteria

package/docs/vgxcode.md

@@ -0,0 +1,87 @@
+# VGXNESS Code OpenTUI shell (`vgxcode`)
+
+Experimental Bun/OpenTUI coding interface for VGXNESS Code.
+
+**Naming rule:** `VGXNESS Code` is the public product/runtime surface (`vgxness code ...`; `vgx code ...` remains a compatibility alias). `vgxcode` is the internal root-owned OpenTUI shell that renders and drives that runtime during repository development.
+
+## Why this is root-owned
+
+VGXNESS ships the existing `vgxness`/`vgx` CLI bins while the OpenTUI coding interface remains an internal root-owned surface. The repository root owns `@opentui/core`, the Bun lockfile, and verification.
+
+This keeps the shipped `vgxness`/`vgx` CLI stable while letting us build the OpenTUI experience directly from root source.
+
+## Run
+
+Prerequisite: install Bun.
+
+```bash
+bun src/cli/tui/opentui/code/index.ts
+```
+
+Interactive mode starts in read-only `inspect`. Type a task/question and press `Enter`; `vgxcode` runs the root Bun CLI bridge as one of:
+
+```bash
+bun run cli:bun -- code inspect "<your prompt>" --events-jsonl
+bun run cli:bun -- code plan "<your prompt>" --events-jsonl
+bun run cli:bun -- code craft-preview "<your prompt>" --events-jsonl
+bun run cli:bun -- code craft "<your prompt>" --events-jsonl --approval-channel stdio
+```
+
+The OpenTUI shell uses `bun run --silent cli:bun -- ...` internally so Bun lifecycle output does not pollute the JSONL event stream.
+
+The prompt defaults to `inspect`. Press `Tab` to toggle between `inspect` and `plan`, or prefix a prompt with `/inspect`, `/plan`, `/craft-preview`, or `/craft`:
+
+```text
+/plan outline a safe implementation
+/inspect summarize the current architecture
+/craft-preview show the diff you would make
+/craft apply the smallest approved fix
+```
+
+After submit, the prompt input is cleared and the submitted prompt remains visible as `Last submitted`. The UI shows explicit `idle`, `running`, `completed`, and `error` states.
+
+`vgxcode` does not own mutation policy. `inspect`, `plan`, and `craft-preview` are read-only/preview paths. `/craft` is approval-capable and may mutate only through the VGXNESS Code runtime and its explicit approval channel; the OpenTUI shell only renders pending approvals and writes approve/deny decisions to the live runtime process.
+
+To replay real read-only runtime events without spawning the root CLI, pipe the root Bun CLI JSONL bridge into `vgxcode`:
+
+```bash
+bun run cli:bun -- code inspect "What is this project?" --events-jsonl | bun src/cli/tui/opentui/code/index.ts
+bun run cli:bun -- code plan "Plan a safe change" --events-jsonl | bun src/cli/tui/opentui/code/index.ts
+bun run cli:bun -- code craft-preview "Preview a safe change" --events-jsonl | bun src/cli/tui/opentui/code/index.ts
+```
+
+Use `bun run cli:bun -- ...` for OpenTUI-adjacent local testing. `npm run cli -- ...` uses Node/tsx and can fail when a path loads `@opentui/core`.
+
+Press `Ctrl+C` to exit.
+
+## Current scope
+
+The shell reads newline-delimited `CodeRuntimeEvent` JSON from stdin when piped. If stdin has events or parse errors, `vgxcode` renders that stream and does not spawn the root CLI. If stdin is a TTY, the OpenTUI entrypoint opens the interactive prompt and uses `inspect` by default through the JSONL bridge.
+
+Errors are shown in the Activity panel when JSONL parsing fails, unsupported runtime events appear, npm/lifecycle banners appear in the stream, or the spawned root CLI exits non-zero.
+
+## Checks
+
+```bash
+npm run check:bun-lock          # from the repository root; read-only/advisory
+bun run verify:typecheck
+node --import tsx --test test/cli/tui/opentui-code.test.ts
+bun run smoke:opentui-code
+```
+
+The root `npm run check:bun-lock` command compares root `package.json`
+dependency specifiers with the root `bun.lock` without installing Bun or
+mutating `node_modules`. The root lockfile is the repository dependency
+authority; package evidence is validated by `bun run package:bun:evidence`.
+
+Manual interactive check:
+
+```bash
+bun src/cli/tui/opentui/code/index.ts
+# type: What is this project?
+# press Enter
+```
+
+## Safety rule
+
+`vgxcode` renders state and user decisions. It must not execute tools directly, bypass approvals, or own mutation policy. Runtime, approvals, verification, SDD, and memory stay in the VGXNESS core runtime.

package/docs/vgxness-code.md

@@ -2,12 +2,14 @@
 
 VGXNESS Code is the native VGXNESS coding CLI/runtime. It is not an OpenCode wrapper, fork, compatibility layer, config format, prompt copy, or branded re-skin. Provider adapters translate VGXNESS-native requests only.
 
+`vgxcode` is the internal root-owned OpenTUI shell for VGXNESS Code development. Public commands stay under `vgxness code ...`; the OpenTUI shell should render runtime state and approval decisions without becoming a separate mutation policy layer.
+
 ## Commands
 
-- `vgx code inspect "<question>"` — read-only repository investigation.
-- `vgx code plan "<task>"` — read-only implementation planning.
-- `vgx code craft "<task>"` — bounded edit-capable work with approval gates.
-- `vgx code sdd <change> <phase>` — SDD-backed phase work; use `--save-artifact` only when persistence is intended.
+- `vgxness code inspect "<question>"` — read-only repository investigation.
+- `vgxness code plan "<task>"` — read-only implementation planning.
+- `vgxness code craft "<task>"` — bounded edit-capable work with approval gates.
+- `vgxness code sdd <change> <phase>` — SDD-backed phase work; use `--save-artifact` only when persistence is intended.
 
 Useful controls: `--provider`, `--model`, `--stream`, `--json`, `--max-source-bytes`, `--approval-policy ask|allow|deny`, `--verification none|suggest|run|repair`, `--transcript off|summary|full`, and `--memory off|ask|auto`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -21,7 +21,8 @@
   "type": "module",
   "scripts": {
     "cli": "tsx src/cli/index.ts",
-    "build": "tsc -p tsconfig.build.json && node scripts/copy-migrations.mjs",
+    "cli:bun": "bun src/cli/index.ts",
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json && node scripts/copy-migrations.mjs",
     "verify": "bun run verify:typecheck && bun run verify:test && bun run verify:test:bun-storage && bun run verify:bun-sqlite && bun run verify:package",
     "verify:typecheck": "tsc --noEmit",
     "verify:test": "node scripts/run-node-tests.mjs",
@@ -30,11 +31,11 @@
     "verify:bun-sqlite": "bun scripts/probe-bun-sqlite.mjs",
     "ci:bun": "bun run check:bun-lock && bun run verify",
     "check:bun-lock": "node scripts/check-bun-lock.mjs",
-    "check:vgxcode:bun-lock": "node scripts/check-bun-lock.mjs --package-json packages/vgxcode/package.json --bun-lock packages/vgxcode/bun.lock",
     "check:bun:typecheck": "node scripts/run-bun-typecheck.mjs",
     "probe:bun": "node scripts/probe-bun-compat.mjs",
     "probe:bun-runtime": "node scripts/probe-bun-runtime-cli-mcp.mjs",
     "verify:bun-runtime": "node scripts/probe-bun-runtime-cli-mcp.mjs --require-pass",
+    "smoke:opentui-code": "bun src/cli/tui/opentui/code/smoke.ts",
     "package:bun:evidence": "node scripts/probe-bun-package-evidence.mjs",
     "test": "node scripts/run-node-tests.mjs",
     "typecheck": "tsc --noEmit"
@@ -53,13 +54,11 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "ink": "^7.0.3",
-    "react": "^19.2.6",
+    "@opentui/core": "^0.2.16",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^22.15.18",
-    "@types/react": "^19.2.15",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3"
   },