vgxness 1.9.3 → 1.9.5

package/dist/setup/providers/opencode-setup-adapter.js

@@ -61,8 +61,8 @@ export const openCodeSetupAdapter = {
             writesProviderConfig: false,
             summary: contract.status === 'would_install'
                 ? contract.overwriteVgxness
-                    ? `OpenCode ${contract.action} reinstall plan is available; confirmed apply overwrites VGXNESS entries only, preserves unrelated config, and creates managed backups for existing targets.`
-                    : `OpenCode ${contract.action} plan is available for external application; confirmed merges create managed VGXNESS backups.`
+                    ? `OpenCode ${contract.action} reinstall plan is available; confirmed apply overwrites VGXNESS entries only, preserves unrelated config, sets permission.bash=allow, and creates managed backups for existing targets.`
+                    : `OpenCode ${contract.action} plan is available for external application; confirmed applies mcp.vgxness and permission.bash=allow, and creates managed VGXNESS backups when merging.`
                 : contract.message,
             ...(targetPath !== undefined ? { targetPath } : {}),
             warnings: contract.warnings,
@@ -122,7 +122,7 @@ function openCodePlanPreview(visibility, plan) {
             targetPath: source.targetPath,
             backupRequired: source.backupRequired,
             confirmationRequired: Boolean(plan?.actions.some((candidate) => candidate.safety.requiresExplicitConfirmation)),
-            risks: source.overwriteVgxness ? overwriteInstallRisks(source.installsAgents) : source.action === 'create' ? createInstallRisks() : mergeInstallRisks(),
+            risks: [...(source.overwriteVgxness ? overwriteInstallRisks(source.installsAgents) : source.action === 'create' ? createInstallRisks() : mergeInstallRisks()), ...bashPermissionRisks(source.allowBash)],
             warnings: source.warnings,
         };
     }
@@ -154,6 +154,9 @@ function overwriteInstallRisks(installsAgents) {
         'OpenCode must be restarted after external installation before it discovers the updated vgxness MCP server.',
     ];
 }
+function bashPermissionRisks(allowBash) {
+    return allowBash === true ? ['OpenCode permission.bash is set to allow by default, so terminal commands may run without prompting after restart.'] : [];
+}
 function refusedRepairRisks(message) {
     return [
         `Install planner refused automatic repair: ${message}`,
@@ -176,8 +179,8 @@ function externalInstallAction(scope, targetPath, overwriteVgxness = false) {
         kind: 'copy-command',
         command: ['vgxness', 'mcp', 'install', 'opencode', '--scope', scope, '--yes', ...(overwriteVgxness ? ['--overwrite-vgxness'] : [])],
         description: overwriteVgxness
-            ? 'Copy and run this outside the TUI only after reviewing that VGXNESS entries will be overwritten and unrelated config preserved.'
-            : 'Copy and run this outside the TUI only after reviewing the read-only plan.',
+            ? 'Copy and run this outside the TUI only after reviewing that VGXNESS entries will be overwritten, unrelated config preserved, and bash allowed without prompts.'
+            : 'Copy and run this outside the TUI only after reviewing the read-only plan and bash permission risk.',
         safety: externalProviderWriteSafety(targetPath),
     };
 }

package/dist/setup/setup-plan.js

@@ -131,6 +131,7 @@ function setupPlanFromOpenCode(input) {
                 installsAgents: input.opencode.installsAgents,
                 agentNames: input.opencode.agentNames,
                 ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
+                ...(input.opencode.allowBash ? { allowBash: true } : {}),
             },
             actions: [],
             conflicts: [
@@ -158,11 +159,12 @@ function setupPlanFromOpenCode(input) {
             installsAgents: input.opencode.installsAgents,
             agentNames: input.opencode.agentNames,
             ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
+            ...(input.opencode.allowBash ? { allowBash: true } : {}),
         },
         actions: [
             {
                 id: `opencode-${input.opencode.action}`,
-                description: `${input.opencode.overwriteVgxness ? 'Reinstall/overwrite VGXNESS entries in' : input.opencode.action === 'create' ? 'Create' : 'Merge'} OpenCode config with mcp.vgxness using vgxness mcp start${input.installMode === 'mcp-plus-agents' ? ' and manager/SDD agents' : ''}${input.opencode.overwriteVgxness ? '; unrelated OpenCode config is preserved' : ''}.`,
+                description: `${input.opencode.overwriteVgxness ? 'Reinstall/overwrite VGXNESS entries in' : input.opencode.action === 'create' ? 'Create' : 'Merge'} OpenCode config with mcp.vgxness using vgxness mcp start${input.installMode === 'mcp-plus-agents' ? ' and manager/SDD agents' : ''}${input.opencode.overwriteVgxness ? '; unrelated OpenCode config is preserved' : ''}${input.opencode.allowBash ? '; sets permission.bash to allow by default' : ''}.`,
                 mutating: false,
                 targetPath: input.opencode.targetPath,
                 backupRequired: input.opencode.backupRequired,

package/dist/status/product-status.js

@@ -82,7 +82,11 @@ function fromSddCockpit(cockpit, project, baseSafety, relatedRunContext) {
         blockers: cockpit.aggregateBlockers.length === 0
             ? ['none']
             : cockpit.aggregateBlockers.map((blocker) => `${blocker.phase}: ${blocker.reason} at ${blocker.topicKey}${blocker.action === undefined ? '' : `; action=${blocker.action}`}`),
-        next: [cockpit.recommendedAction],
+        next: [
+            cockpit.next.status === 'runnable' && cockpit.next.nextPhase !== undefined
+                ? `Continue the ${cockpit.next.nextPhase} phase in OpenCode using VGXNESS MCP and hidden SDD subagents.`
+                : cockpit.recommendedAction,
+        ],
         command,
         sddNextStatus: cockpit.next.status,
         ...(relatedRunContext === undefined ? {} : { relatedRunContext }),

package/docs/cli.md

@@ -49,7 +49,7 @@ Release defaults used by the guided setup are:
 - Install mode: MCP plus manager/SDD agents (`mcp-plus-agents`).
 - Public CLI language: English.
 
-Recommended user flow after `npm install -g vgxness`:
+Recommended bootstrap and diagnostic flow after `npm install -g vgxness`:
 
 ```bash
 vgxness --help
@@ -59,30 +59,35 @@ vgxness setup plan           # human-readable, read-only plan
 vgxness setup status         # human-readable, read-only setup status
 vgxness setup apply --yes    # writes OpenCode config only after explicit consent
 vgxness doctor               # human-readable readiness checks
-vgxness status --project <project> --change <change>
-vgxness next --project <project> --change <change>
+vgxness status --project <project> --change <change>   # diagnostic cockpit
+vgxness next --project <project> --change <change>     # diagnostic/recovery next step
+vgxness sdd continue --project <project> --change <change> # read-only manual continuation plan
 vgxness resume --project <project> --run-id <id>
 vgxness setup rollback --backup <path>
 ```
 
+Daily SDD phase progression is OpenCode-first: talk to OpenCode with the VGXNESS MCP server installed, and let the hidden SDD subagents use MCP tools for phase work. The CLI and TUI remain supported for bootstrap/setup, diagnostics, recovery, manual fallback, and scripting; they are not the primary daily surface.
+
 `setup plan`, `setup status`, and non-TTY `init` planning do not write provider config. Local VGXNESS store initialization may occur when the selected SQLite store is needed. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default OpenCode target is `$HOME/.config/opencode/opencode.json`; pass `--scope project` to opt into `<workspace>/.opencode/opencode.json`. `setup apply --yes` is the explicit OpenCode provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
 
-`vgxness init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, OpenCode scope, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
+`vgxness init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, OpenCode scope, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd cockpit`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
+
+`vgxness sdd cockpit --json` returns the same additive compatibility shape as the MCP cockpit: all existing raw `SddCockpit` top-level fields remain present, with an additional top-level `readModel`. The cockpit is read-only and metadata-only: it does not include artifact bodies, infer acceptance from artifact presence, advance phases, execute acceptance, call providers, or write provider config. Text output renders from read-model concepts such as next action, phase metadata, blockers, guidance, and `Content included: no`.
 
 ## Daily workflow front doors
 
-Use these top-level commands before dropping into lower-level SDD or run inspection commands:
+Use OpenCode conversation + VGXNESS MCP + hidden SDD subagents for normal daily SDD work. Use these top-level commands when you need diagnostics, recovery, manual fallback, or scriptable state inspection:
 
 | Question | Command | Purpose |
 |---|---|---|
-| Where am I? | `vgxness status --project <project> --change <change>` | Shows the SDD cockpit state, blockers, next recommendation, and safety notes. |
-| What should I do now? | `vgxness next --project <project> --change <change>` | Narrows the cockpit to the next action and why it is safe or blocked. |
-| How do I continue a change? | `vgxness sdd continue --project <project> --change <change>` | Builds a read-only continuation plan for the selected SDD change. |
+| Where am I? | `vgxness status --project <project> --change <change>` | Diagnostic cockpit state, blockers, next recommendation, and safety notes. |
+| What should I do now? | `vgxness next --project <project> --change <change>` | Recovery/diagnostic next action and why it is safe or blocked. |
+| How do I continue a change manually? | `vgxness sdd continue --project <project> --change <change>` | Builds a read-only continuation plan and manual fallback commands for the selected SDD change. |
 | How do I continue interrupted work? | `vgxness resume --project <project> [--run-id <id>]` | Lists or inspects interrupted runs and suggests manual continuation commands without retrying anything. |
 
 Without `--change`, `--project`, or `--run-id`, these commands stay orientation-only and do not open the local memory store. With a selected change, project, or run, top-level `status`, `next`, and `resume` inspect SQLite read-only; formal `sdd` commands are non-provider, non-run-executing planning/artifact commands that may use the normal local store path. Pass `--json` for automation.
 
-The usual SDD operator loop is: inspect `status`, ask `next`, run `sdd continue` for the copyable continuation plan, then either run `vgxness code sdd ...` for phase work or `vgxness resume ...` for an interrupted run. After a draft is ready, use `sdd accept-artifact` for explicit human acceptance; if an artifact was rejected, use `sdd reopen-artifact` before revising it. Related interrupted run hints in `status`, `next`, and `sdd continue` are advisory only; they help avoid duplicate work but do not retry or execute runs.
+The usual SDD operator loop happens inside OpenCode: continue the phase in conversation while VGXNESS MCP and hidden SDD subagents inspect readiness, persist artifacts, and report evidence. CLI commands remain fallback/recovery tools: inspect `status`, ask `next`, run `sdd continue` for a copyable manual continuation plan, then either run `vgxness code sdd ...` as an explicit fallback or `vgxness resume ...` for interrupted work. After a draft is ready, use `sdd accept-artifact` for explicit human acceptance; if an artifact was rejected, use `sdd reopen-artifact` before revising it. Related interrupted run hints in `status`, `next`, and `sdd continue` are advisory only; they help avoid duplicate work but do not retry or execute runs.
 
 ## Bun-first repository verification
 
@@ -237,7 +242,7 @@ bun run cli:bun --
 
 The installed `vgxness`/`vgx` binary opens the OpenTUI main menu when run with no arguments in a TTY. With no TTY, no-args prints deterministic safe setup guidance, exits 0, and does not infer a project, open project state, toggle raw mode, or write provider/config artifacts. Use `vgxness --help` or `vgxness -h` to print command help without starting the main menu; explicit subcommands keep their normal behavior.
 
-The top-level menu is: **Installation, Doctor / recovery, SDD / workflow guidance, Advanced CLI, Exit**. Terminal controls are `↑/↓` or `j/k` to move, `Enter` to open the focused item, `?` for help, and `q` to quit.
+The top-level menu is: **Installation, Doctor / recovery, SDD / workflow guidance, Advanced CLI, Exit**. It is a read-only setup, diagnostics, recovery, and fallback surface; daily SDD progression stays in OpenCode with VGXNESS MCP. Terminal controls are `↑/↓` or `j/k` to move, `Enter` to open the focused item, `?` for help, and `q` to quit.
 
 For scriptable status, use explicit read-only commands:
 
@@ -255,7 +260,7 @@ Provider support shown in the Installation surface is:
 - **Antigravity** — placeholder/coming-soon guidance only.
 - **Custom/future** — extension point with safe manual/default unsupported behavior.
 
-Setup and main-menu TUI surfaces do **not** silently write OpenCode or other provider config, do **not** call provider executables, and do **not** approve/reject preflights. Any operational next action is copied for explicit execution outside the TUI.
+Setup and main-menu TUI surfaces do **not** silently write OpenCode or other provider config, do **not** call provider executables, and do **not** approve/reject preflights. They print diagnostics, recovery hints, and manual fallback commands; daily SDD work should continue in OpenCode.
 
 ## Natural-language orchestrator preview
 
@@ -562,7 +567,7 @@ Manual/opt-in runtime validation checklist (not normal CI):
 
 ## SDD workflow examples
 
-Use `sdd` commands to inspect local SDD artifact state and save, read, or list phase artifacts. These commands read and write only the selected `vgxness` local SQLite memory store: `--db <path>` when passed, `VGXNESS_DB_PATH` when set, or the global default database when neither override is present.
+Use OpenCode conversation with VGXNESS MCP and hidden SDD subagents for normal daily SDD progression. Use `sdd` commands to inspect local SDD artifact state and save, read, or list phase artifacts for diagnostics, recovery, scripting, or manual fallback. These commands read and write only the selected `vgxness` local SQLite memory store: `--db <path>` when passed, `VGXNESS_DB_PATH` when set, or the global default database when neither override is present.
 
 ```bash
 bun run cli:bun -- sdd status --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
@@ -579,13 +584,13 @@ bun run cli:bun -- sdd reopen-artifact --project vgxness --change sdd-workflow-e
 VGXNESS_DB_PATH=/tmp/vgxness-memory.sqlite bun run cli:bun -- sdd list-artifacts --project vgxness --change sdd-workflow-engine
 ```
 
-Current canonical phases are `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, and `archive`. `apply` is accepted as a user-facing input alias, but artifacts, topic keys, readiness/status/cockpit JSON, and internal metadata continue to use canonical `apply-progress`. Each artifact is stored under `sdd/{change}/{phase}` in the local SQLite memory store. `sdd status` reports which phase artifacts are present, blocker-specific next actions, and related interrupted run hints when available. `sdd next` reports the next SDD action for a project/change. `sdd continue` turns that state into a read-only continuation plan, including draft-run suggestions for planning phases and related interrupted run context when a matching stopped run exists. `sdd status`, `sdd next`, `sdd continue`, `sdd get-artifact`, and `sdd list-artifacts` are human-readable by default; pass `--json` for automation/stable structured output. `sdd ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` shows artifact metadata and then full content after `--- Content ---`; `sdd list-artifacts` shows one compact row for every canonical SDD phase in phase order and does not print full artifact content.
+Current canonical phases are `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, and `archive`. `apply` is accepted as a user-facing input alias, but artifacts, topic keys, readiness/status/cockpit JSON, and internal metadata continue to use canonical `apply-progress`. Each artifact is stored under `sdd/{change}/{phase}` in the local SQLite memory store. `sdd status` reports which phase artifacts are present, blocker-specific next actions, and related interrupted run hints when available. `sdd next` reports the next SDD action for a project/change and frames runnable phase work as OpenCode-first while preserving fallback command fields. `sdd continue` turns that state into a read-only continuation plan, including manual fallback commands, draft-run suggestions for planning phases, and related interrupted run context when a matching stopped run exists. `sdd status`, `sdd next`, `sdd continue`, `sdd get-artifact`, and `sdd list-artifacts` are human-readable by default; pass `--json` for automation/stable structured output. `sdd ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` shows artifact metadata and then full content after `--- Content ---`; `sdd list-artifacts` shows one compact row for every canonical SDD phase in phase order and does not print full artifact content.
 
 `sdd accept-artifact` records explicit human-only acceptance of an existing artifact through the same SDD workflow service used by MCP. It requires `--project`, `--change`, `--phase`, and `--actor`; `--display-name` defaults to the actor id. `--accepted-at` is optional, but when supplied it must be an ISO date-time with an explicit timezone (`Z` or offset) and is normalized to UTC `toISOString()` output. The default output is a human-readable confirmation with a JSON hint; `--json` returns a content-free success object with project/change/phase/topic key/artifact id/status/acceptedBy/acceptedAt and optional note. `save-artifact` creates or updates draft content only and does not imply acceptance. `sdd reopen-artifact` moves a rejected artifact back to draft after an explicit human decision, so the artifact can be revised and accepted again.
 
 Use `resume --project <project>` when you do not know the run id. It lists recent interrupted candidates for that project from the selected database. Use `resume --project <project> --run-id <id>` to inspect one candidate; this is still read-only and advisory.
 
-The SDD CLI is status, planning, and artifact persistence only. It does **not** execute providers, retry workflow runs, create `openspec/`, or write `.opencode/`, `.claude/`, or user/global provider config.
+The SDD CLI is status, planning, artifact persistence, diagnostics, recovery, scripting, and manual fallback only. It does **not** execute providers, retry workflow runs, create `openspec/`, or write `.opencode/`, `.claude/`, or user/global provider config.
 
 ## Agent resolution
 

package/docs/mcp.md

@@ -25,7 +25,7 @@ All tools:
 | `vgxness_sdd_reopen_artifact` | Move a rejected artifact back to draft for revision. | `project`, `change`, `phase`, `reopenedBy` (`{type:"human", id, displayName?}`); optional `reopenedAt`, `note`, `runId`, `agentId` | Human-only recovery path. Does not imply acceptance or bypass downstream gates. |
 | `vgxness_sdd_get_artifact` | Read one full artifact. | `project`, `change`, `phase`; optional `payloadMode` (`compact`/`verbose`) | |
 | `vgxness_sdd_list_artifacts` | List all artifacts for a change in canonical phase order. | `project`, `change`; optional `payloadMode` | |
-| `vgxness_sdd_cockpit` | Aggregate per-phase status, blockers, and recommended next action. | `project`, `change` | Returns `SddCockpit` with `aggregateBlockers` of kinds `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, `readiness`. |
+| `vgxness_sdd_cockpit` | Aggregate per-phase status, blockers, and recommended next action. | `project`, `change` | Returns the raw `SddCockpit` compatibility fields plus additive top-level `readModel`. The response is read-only and metadata-only: no artifact bodies, no phase advancement, no provider/config writes. `readModel.contentIncluded` is always `false`; accepted means explicit human acceptance, not artifact presence. |
 | `vgxness_governance_report` | Build a redacted governance report for a project/change/run. | `project`; optional `change`, `runId`, `workflow`, `phase`, `agentId`, `agent` (with `id`, `name`, `mode`, `scope`), `payloadMode` | See [Safety model](./safety.md) for redaction rules. |
 
 ## Memory (4)
@@ -114,7 +114,7 @@ vgxness_sdd_continue   { project: "vgxness", change: "new-flow" }
 vgxness_sdd_get_readiness { project: "vgxness", change: "new-flow", phase: "proposal" }
 ```
 
-The cockpit returns `aggregateBlockers`; if any are `unaccepted-phase`, the agent should not run the next phase until a human accepts the prerequisite. `vgxness_sdd_continue` uses the same SDD state to explain how to continue; it is advisory only.
+The cockpit preserves raw `SddCockpit` fields such as `phases`, `artifacts`, `aggregateBlockers`, and `inspectCommand`, and also adds `readModel` for stable UI/MCP consumption. Both raw artifact summaries and `readModel.phases[].artifact` omit artifact bodies. If any raw blocker is `unaccepted-phase`, or any read-model phase has `acceptance.acceptedByHuman: false`, do not treat the prerequisite as accepted merely because an artifact exists. `vgxness_sdd_continue` uses the same SDD state to explain how to continue; it is advisory only.
 
 Recording a phase with explicit human acceptance:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {