vgxness 1.3.0 → 1.3.1

package/docs/funcionamiento-del-sistema.md

@@ -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. |
@@ -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:
@@ -644,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
@@ -714,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.
@@ -722,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.
@@ -730,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`.
@@ -738,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:
@@ -750,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`.
@@ -758,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.

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

package/docs/vgxcode.md

@@ -1,12 +1,14 @@
-# vgxcode OpenTUI root-owned shell
+# VGXNESS Code OpenTUI shell (`vgxcode`)
 
-Experimental Bun/OpenTUI coding interface for VGXNESS.
+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 `vgx`/`vgxness` CLI bins while the OpenTUI coding interface remains an internal root-owned surface. The repository root owns `@opentui/core`, the Bun lockfile, and verification.
+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 `vgx`/`vgxness` CLI stable while letting us build the OpenTUI experience directly from root source.
+This keeps the shipped `vgxness`/`vgx` CLI stable while letting us build the OpenTUI experience directly from root source.
 
 ## Run
 
@@ -16,27 +18,36 @@ Prerequisite: install Bun.
 bun src/cli/tui/opentui/code/index.ts
 ```
 
-Interactive mode is read-only. Type a task/question and press `Enter`; `vgxcode` runs the root CLI bridge as either:
+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 prompt defaults to `inspect`. Press `Tab` to toggle between `inspect` and `plan`, or prefix a prompt with `/inspect` or `/plan`:
+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. It is intentionally mutation-disabled: no `craft`, no SDD writes, and no approval flow lives in this internal shell.
+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`.
@@ -45,7 +56,7 @@ 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 read-only `inspect` through the JSONL bridge.
+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.
 
@@ -73,4 +84,4 @@ bun src/cli/tui/opentui/code/index.ts
 
 ## Safety rule
 
-`vgxcode` renders state. It must not execute tools, bypass approvals, or own mutation policy. Runtime, approvals, verification, SDD, and memory stay in the VGXNESS core runtime.
+`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.3.0",
+  "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": {