vgxness 1.5.1 → 1.6.0

package/docs/cli.md

@@ -232,7 +232,7 @@ bun run cli:bun -- sdd status --project vgxness --change my-change
 Provider support shown in the Installation surface is:
 
 - **OpenCode** — supported primary provider with preview/status/doctor and read-only install planning.
-- **Claude** — preview-only guidance; no install/apply action is exposed.
+- **Claude** — supported secondary provider for Claude CLI MCP registration, project `.mcp.json` compatibility, project-root `CLAUDE.md` managed memory, and project/user agent planning. Scopes are `local|project|user`; `personal`/`global` map to `user`. Explicit guarded apply is outside the guided OpenCode flow and requires `mcp install claude --scope <scope> --yes --run-id <id>`. Read-only status/doctor/change-plan do not read private Claude config or execute Claude Code.
 - **Antigravity** — placeholder/coming-soon guidance only.
 - **Custom/future** — extension point with safe manual/default unsupported behavior.
 
@@ -254,6 +254,45 @@ The command prints a deterministic JSON envelope with `flow`, `confidence`, `rea
 
 Safety boundary: this is a preview only. It does **not** call providers, edit files, write provider config, create runs, run installers, install global memory, or create `openspec/`. Preview actions are labels/manual commands for review, not executed steps.
 
+## Code runtime CLI (`vgxness code`)
+
+`vgxness code` is the native workspace runtime for bounded agentic work. It is not a wrapper around OpenCode or any provider; provider adapters translate VGXNESS-native requests only. See [Code runtime](./code-runtime.md) for the full contract; this section lists the CLI surface.
+
+Modes (read-only by default unless `--approval-channel` and `--approval-policy` are passed):
+
+| Mode | Purpose | Mutations |
+|---|---|---|
+| `inspect` | Read-only investigation of the workspace. | None. |
+| `plan` | Read-only implementation planning. | None. |
+| `craft-preview` | Show the diff that would be applied. | None. |
+| `craft` | Approval-gated, bounded edit-capable work. | Edits, shell, network, git, SDD persistence all routed through explicit policy decisions. |
+
+Common flags across modes:
+
+```bash
+vgxness code inspect "<question>"   \
+  --provider openai-compatible      \  # or "fake" for offline testing
+  --model <model-id>                 \
+  --stream                           \  # emit JSONL runtime events as they happen
+  --json                             \  # final response as JSON
+  --max-source-bytes <bytes>         \  # bound on sources loaded into prompt
+  --approval-policy ask|allow|deny   \
+  --approval-channel stdio|auto      \
+  --verification none|suggest|run|repair \
+  --transcript off|summary|full      \
+  --memory off|ask|auto
+```
+
+SDD-aware mode is exposed through `vgxness code sdd <change> <phase>`; pass `--save-artifact` only when persistence is intended, and pass `--change-id`/`--phase` to scope work. Read-only phases stay artifact-oriented; `apply-progress` may expose edit and shell tools; `verify` may expose verification shell tools.
+
+Useful events-only output for piping into the OpenTUI shell or your own tooling:
+
+```bash
+vgxness code inspect "Summarize the current architecture" --events-jsonl
+```
+
+Safety boundary: `inspect`, `plan`, and `craft-preview` never mutate. `craft` may only mutate through the permission-aware executors and the explicit approval channel; it never writes outside the workspace, never pushes to remote, and never edits `openspec/`. Secret-like values are redacted from prompts, transcripts, checkpoints, and memory saves. See [Safety model](./safety.md).
+
 ## Workflow CLI
 
 Use workflow commands when you want an explicit operator-controlled path from intent classification to a recorded run and, optionally, a guarded execution request. Supported workflows are `explore`, `quickfix`, `plan`, `build`, `debug`, and `sdd`:
@@ -406,7 +445,7 @@ bun run cli:bun -- mcp setup --preview --provider claude --db <path>
 bun run cli:bun -- mcp doctor --db <path> --project vgxness --change manual-smoke
 ```
 
-The setup preview JSON includes `installable:false`, `readOnly:true`, `writesProviderConfig:false`, plus a copyable MCP server command. Without `--db`, preview snippets omit `--db` and rely on the global default database; with `--db <path>` or `VGXNESS_DB_PATH`, snippets keep the explicit database argument. If needed, copy the `server.command` and `server.args` from the preview into your client manually; the preview itself never writes that config. For OpenCode config automation, inspect `mcp install opencode --plan` before applying with `--yes`; the default target is `$HOME/.config/opencode/opencode.json`.
+The setup preview JSON includes `installable:false`, `readOnly:true`, `writesProviderConfig:false`, plus a copyable MCP server command. Without `--db`, preview snippets omit `--db` and rely on the global default database; with `--db <path>` or `VGXNESS_DB_PATH`, snippets keep the explicit database argument. If needed, copy the `server.command` and `server.args` from the preview into your client manually; the preview itself never writes that config. For OpenCode config automation, inspect `mcp install opencode --plan` before applying with `--yes`; the default target is `$HOME/.config/opencode/opencode.json`. For Claude config, inspect `mcp install claude --plan --scope local|project|user`; confirmed writes or CLI execution require `mcp install claude --scope <scope> --yes --run-id <id>` so VGXNESS run preflight can authorize each target.
 
 The top-level `vgxness doctor` command prints human-readable readiness checks by default and accepts `--json` for scriptable output. Lower-level `mcp doctor` remains useful for MCP-specific checks and manual diagnostics; use `--json` where parseable output is needed. `ready:true` means required checks passed. `ready:false` means at least one required check failed; read the failed check `id`, `detail`, and optional `remediation` to fix the local setup, then run doctor again.
 
@@ -467,6 +506,41 @@ Manual OpenCode verification checklist:
 5. In OpenCode, confirm the `vgxness` MCP tools are available.
 6. Call `vgxness_sdd_status` against a known project/change, then run doctor again if anything fails.
 
+## Claude Code MCP install
+
+Claude Code is supported as a secondary, non-default provider for VGXNESS MCP/subagent configuration. Planning/status/doctor/change-plan are read-only and do not require Claude Code, network, or credentials. Scopes are `local`, `project`, and `user`; compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as Claude CLI argv (`claude mcp add --scope <scope> vgxness -- vgxness mcp start`), never shell strings or manual `~/.claude.json` mutation.
+
+```bash
+bun run cli:bun -- mcp install claude --plan --scope project --db <path>
+bun run cli:bun -- mcp install claude --plan --scope user --db <path>
+bun run cli:bun -- mcp install claude --yes --scope project --run-id <id> --db <path>
+```
+
+Allowed project-scope writes after explicit confirmation and run preflight:
+
+- `.mcp.json`
+- `.claude/agents/*.md`
+- project-root `CLAUDE.md`, only the VGXNESS managed block; user-authored content outside the block is preserved and existing files are backed up before append/update
+
+User agent files target `~/.claude/agents/*.md` only when a future apply path explicitly preflights that external directory. Read-only plans/status/doctor/change-plan never write it.
+
+Forbidden writes:
+
+- `~/.claude.json`
+- `.claude/CLAUDE.md`
+
+Malformed or conflicting VGXNESS markers in project-root `CLAUDE.md` refuse the full Claude project install before any Claude target is mutated.
+
+Manual/opt-in runtime validation checklist (not normal CI):
+
+1. Apply Claude project-local config through the guarded VGXNESS flow.
+2. Open Claude Code in the project manually.
+3. Approve the project MCP server if prompted.
+4. Run `/mcp` and verify `vgxness` is connected.
+5. Run `/agents` and verify expected project subagents are visible.
+6. Ask Claude to call a safe read-only VGXNESS MCP tool.
+7. Confirm forbidden files were not written by VGXNESS.
+
 ## 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.
@@ -872,3 +946,17 @@ Existing project-local stores remain compatible; opt in explicitly when needed:
 ```bash
 bun run cli:bun -- memory search --project vgxness --db .vgx/memory.sqlite
 ```
+
+For more on schema, scopes, and lifecycle, see [Storage](./storage.md).
+
+## See also
+
+- [Architecture](./architecture.md) — current-state architecture and core domain model.
+- [Code runtime](./code-runtime.md) — `vgxness code` modes, tools, providers, and approval flow.
+- [MCP tools](./mcp.md) — full reference for the 38 MCP tools exposed to agents.
+- [Safety model](./safety.md) — permission categories, approval flow, redactors, and runtime gates.
+- [Storage](./storage.md) — SQLite schema, scopes, and lifecycle.
+- [Providers](./providers.md) — adapter contract and how to add a new provider.
+- [Roadmap](./roadmap.md) — planned work not yet shipped.
+- [Contributing](./contributing.md) — repository layout, verification, and style.
+- [Glossary](./glossary.md) — terminology used across the docs and the codebase.

package/docs/code-runtime.md

@@ -0,0 +1,218 @@
+# VGXNESS Code runtime (`vgxness code`)
+
+`vgxness code` is the native VGXNESS coding CLI/runtime. It is not a wrapper around OpenCode, a fork, a compatibility layer, a config format, a prompt copy, or a branded re-skin. Provider adapters translate VGXNESS-native requests only.
+
+`vgxcode` is the experimental OpenTUI shell that renders `vgxness code` runtime events. It is currently root-owned during development; promoted surfaces will move to the standard `vgxness`/`vgx` bins.
+
+## Commands
+
+```bash
+vgxness code inspect "<question>"          # read-only repository investigation
+vgxness code plan "<task>"                 # read-only implementation planning
+vgxness code craft-preview "<task>"        # show the diff you would make
+vgxness code craft "<task>"                # bounded edit-capable work with approval gates
+vgxness code sdd <change> <phase>          # SDD-backed phase work
+```
+
+Common flags across modes:
+
+| Flag | Effect |
+|---|---|
+| `--provider <id>` | `openai-compatible` (default in real use) or `fake` (deterministic for tests). |
+| `--model <id>` | Provider model id. |
+| `--stream` | Emit JSONL runtime events as they happen. |
+| `--json` | Final response as JSON. |
+| `--max-source-bytes <bytes>` | Bound on sources loaded into the prompt. |
+| `--approval-policy ask\|allow\|deny` | Default `ask`. |
+| `--approval-channel stdio\|auto` | `stdio` reads decisions from stdin; `auto` uses the configured broker. |
+| `--verification none\|suggest\|run\|repair` | Verification posture. Default `suggest`. |
+| `--transcript off\|summary\|full` | Final summary contents. Default `summary`. |
+| `--memory off\|ask\|auto` | Memory save posture. Default `off`. |
+| `--events-jsonl` | Output only the JSONL event stream (used for piping into the OpenTUI shell). |
+
+`vgxness code sdd <change> <phase>` accepts:
+
+| Flag | Effect |
+|---|---|
+| `--save-artifact` | Persist the phase artifact when explicit persistence is intended. |
+| `--change-id <id>` | Override change id. |
+| `--approval-policy`, `--approval-channel`, `--memory` | Same as the other modes. |
+
+## Modes
+
+### `inspect`
+
+Read-only repository investigation. The runtime exposes only the `read` tool group: `list_files`, `read_file`, `search_content`, `inspect_project`, `git_status`, `git_diff`, `git_log`. No mutations, no shell, no network, no git writes.
+
+### `plan`
+
+Read-only implementation planning. Same read tool group as `inspect`. The runtime can summarize architecture, propose safe approaches, and produce implementation outlines without touching the workspace.
+
+### `craft-preview`
+
+Show the diff the runtime would apply. The runtime may call read tools and run planning-style reasoning, but does not write. Output is a unified diff that the user can review before approving the actual mutation.
+
+### `craft`
+
+Approval-gated, bounded edit-capable work. Adds the workspace mutation group (`apply_patch`, `create_file`, `update_file`, `delete_file`), the shell/verification group (`run_shell_command`, `run_verification_command`, `network_request`, `git_mutation`), and SDD persistence tools if `--save-artifact` is set. Each mutation routes through `evaluatePermission(...)`; the `ApprovalBroker` either auto-resolves per `--approval-policy` or surfaces a prompt through the configured `approval-channel`.
+
+## Tool groups (19 tools)
+
+The runtime's tool set is defined in `src/code/tools/tool-definitions.ts` and is composed per mode.
+
+### Read-only (7)
+
+| Tool | Category | Notes |
+|---|---|---|
+| `list_files` | `read` | Repository files within the workspace. |
+| `read_file` | `read` | Bounded text read. |
+| `search_content` | `read` | Text content search. |
+| `inspect_project` | `read` | Project metadata: package scripts, config files. |
+| `git_status` | `git` | Inspection only. |
+| `git_diff` | `git` | Inspection only. |
+| `git_log` | `git` | Inspection only. |
+
+### Workspace mutations (4, all confirm-gated)
+
+| Tool | Tier | Notes |
+|---|---|---|
+| `apply_patch` | `confirm`, audit | Bounded unified patch inside the workspace. |
+| `create_file` | `confirm`, audit | New file inside the workspace. |
+| `update_file` | `confirm`, audit | Existing file update. |
+| `delete_file` | `restricted`, audit | Destructive; tighter gate. |
+
+### Shell, verification, network, git mutation (4, confirm-gated)
+
+| Tool | Category | Notes |
+|---|---|---|
+| `run_shell_command` | `shell` | Non-destructive commands; permission-gated. |
+| `run_verification_command` | `shell` | Routed through the permission-aware shell executor. |
+| `network_request` | `network` | Bounded; explicit approval required. |
+| `git_mutation` | `git` | Denied by default unless policy explicitly allows it. |
+
+### SDD reads (5)
+
+| Tool | Notes |
+|---|---|
+| `sdd_status` | Read SDD change status for the active change. |
+| `sdd_get_readiness` | Read readiness for the active phase; does not mutate artifacts. |
+| `sdd_read_artifact` | Read one artifact for the active change. |
+| `sdd_next_phase` | Recommended next phase. |
+| `governance_report` | Redacted SDD governance report snapshot. |
+
+### SDD persistence (3, confirm-gated)
+
+| Tool | Notes |
+|---|---|
+| `sdd_save_artifact` | Saves only when explicit persistence was requested. |
+| `sdd_mark_ready` | Marks the phase ready; only when explicit persistence was requested. |
+| `sdd_accept_artifact` | Records human-only acceptance; agents must not auto-accept. |
+
+The SDD tool set is composed per phase: `apply-progress` exposes edit + shell + verification + persistence; `verify` exposes verification shell tools; other phases stay read/artifact oriented.
+
+## Providers
+
+The runtime is provider-neutral. Adapters implement `CodeProviderAdapter` (`src/code/providers/provider-adapter.ts`):
+
+| Adapter | Status | Notes |
+|---|---|---|
+| `openai-compatible` | Real | Speaks to any OpenAI-compatible endpoint; credentials come from environment references, never embedded. |
+| `fake` | Tests | Deterministic, offline; for unit tests and CI. |
+
+There is no native Anthropic provider in the runtime as of v1.5.1. OpenCode exposes an OpenAI-compatible bridge for Claude models; users who want Claude through `vgxness code` go through that bridge. Adding a native Anthropic provider is tracked in [Roadmap](./roadmap.md).
+
+## Approval flow
+
+`PolicyApprovalBroker`, `StdioApprovalBroker`, and `ConservativePermissionGateway` (in `src/code/runtime/approval-coordinator.ts`) wire approval decisions to the runtime event stream.
+
+```text
+tool call requested
+   │
+   ▼
+PolicyApprovalBroker  ──►  ConservativePermissionGateway.evaluate(...)
+   │                              │
+   │                              ├── allow  → execute, record event
+   │                              ├── ask    → ApprovalPrompt
+   │                              │            ├── stdio channel: read line from stdin
+   │                              │            └── auto channel:   call injected broker
+   │                              └── deny   → record blocked event, return error
+   ▼
+CodeRuntimeEventSink (stream JSONL to consumer)
+```
+
+The `vgxcode` OpenTUI shell is one consumer of the event sink. When `craft` requests approval, the shell renders the prompt and writes the human decision back through the live process.
+
+## Configuration and reporting
+
+Safe defaults are local and conservative:
+
+- Provider: `fake` for offline/CI smoke; `openai-compatible` for real use.
+- Posture: read-only by default unless the mode is `craft` or `craft-preview` was previewed.
+- Approval policy: `ask`.
+- Verification: `suggest`.
+- Transcript: `summary` (checkpoint labels/timestamps only).
+- Memory: `off` (never auto-save learnings).
+- Bounded prompt/context size; no repair loop unless explicitly enabled.
+
+Transcript modes:
+
+- `off` — no transcript in the final summary.
+- `summary` — checkpoint labels/timestamps only.
+- `full` — sanitized checkpoints and tool summaries; command stdout/stderr are omitted by default.
+
+Memory modes:
+
+- `off` — never save learnings.
+- `ask` — prepare a sanitized memory-save checkpoint but do not persist.
+- `auto` — save sanitized learnings only through a configured memory gateway.
+
+Prompts, reports, checkpoints, transcripts, and memory saves redact secret-like values through `omitSensitiveCommandOutput`, `redactJson`, and `redactSecrets` (`src/code/reporting/redaction.ts`).
+
+## SDD mode
+
+`vgxness code sdd <change> <phase>` loads existing artifacts for the requested change/phase and exposes phase-appropriate tools. Non-implementation phases stay read/artifact oriented. `apply-progress` may expose edit and shell tools. `verify` may expose verification shell tools. Artifact saves require explicit `--save-artifact` (or the equivalent runtime flag); passing it is the only way persistence is triggered.
+
+## Project detection
+
+`detectProject()` (in `src/code/runtime/project-detection.ts`) reports repository root, stack hints, config files, and verification presets such as `npm run typecheck` or `npm run test` when package scripts exist. The fake provider is deterministic for local tests.
+
+## OpenTUI shell (`vgxcode`)
+
+The shell reads newline-delimited `CodeRuntimeEvent` JSON from stdin. If stdin has events or parse errors, `vgxcode` renders that stream and does not spawn the CLI. If stdin is a TTY, the OpenTUI entrypoint opens the interactive prompt and uses `inspect` by default.
+
+```bash
+bun src/cli/tui/opentui/code/index.ts
+```
+
+Interactive controls: `Tab` toggles between `inspect` and `plan`; prefix with `/inspect`, `/plan`, `/craft-preview`, or `/craft` to switch. Press `Enter` to submit; `Ctrl+C` to exit. The prompt input is cleared after submit and the submitted prompt remains visible as `Last submitted`. The UI shows explicit `idle`, `running`, `completed`, and `error` states.
+
+Replay real read-only runtime events without spawning the root CLI:
+
+```bash
+bun run cli:bun -- code inspect "What is this project?" --events-jsonl | bun src/cli/tui/opentui/code/index.ts
+```
+
+`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 runtime and its explicit approval channel; the OpenTUI shell only renders pending approvals and writes approve/deny decisions to the live runtime process.
+
+## Safety model
+
+`vgxness code` routes edits, shell, network, git mutation, SDD persistence, and memory saves through explicit policy decisions:
+
+- External workspace edits are denied.
+- Destructive commands require approval.
+- Git mutation is blocked by default unless explicitly approved.
+- Network access requires approval.
+- Secret-like values are redacted from prompts, reports, checkpoints, transcripts, and memory saves.
+- Unrelated user work is preserved (no glob expansion outside the workspace, no `.` rewrites, no recursive deletes without explicit operator intent).
+
+The full contract — categories, approval flow, redactors, retry policy — is in [Safety model](./safety.md).
+
+## Rollout checklist
+
+For projects adopting `vgxness code`:
+
+- **Config**: safe defaults documented; transcript/memory/provider controls exposed (`--transcript`, `--memory`, `--provider`).
+- **Safety**: external edits, destructive shell, git mutation, network, secrets, and unrelated user work are covered by tests under `test/code/`.
+- **Verification**: detected presets reported by `detectProject()`; verification results are honest `pass`/`fail`/`skipped` evidence.
+- **Reporting**: transcripts are configurable and sanitized; sensitive command output is omitted by default.
+- **Provider behavior**: core runtime remains provider-neutral and native VGXNESS Code, not a wrapper around any specific provider.

package/docs/contributing.md

@@ -0,0 +1,120 @@
+# Contributing
+
+VGXNESS is an alpha local-first control plane. The repository follows a few rules that keep the product safe, predictable, and reviewable. This document is for humans and AI assistants who want to change the code, the docs, or both.
+
+## Repository layout
+
+```
+src/
+  agents/         # agent + subagent registry, resolver, canonical manifest
+  cli/            # CLI dispatch, command modules, TUI, OpenTUI
+  code/           # native code runtime (vgxness code)
+  export/         # redaction and export helpers
+  governance/     # governance report builder, overlay fingerprint
+  harness/        # harness-side tool handlers
+  mcp/            # MCP server, schemas, control plane, doctor, OpenCode install
+  memory/         # memory service, SQLite database, migrations
+  orchestrator/   # natural-language planner (preview only)
+  payload/        # payload summary helpers
+  permissions/    # policy evaluator, schemas
+  providers/      # OpenCode provider adapter
+  runs/           # run lifecycle, execution planning, retry, snapshot export
+  sdd/            # SDD workflow service, schema, artifact portability
+  setup/          # setup defaults, plan, lifecycle, backup-rollback
+  skills/         # skill registry, resolver, payload, improvement proposals
+  verification/   # verification plan + report services
+  workflows/      # workflow registry, executor, allowlist adapter
+
+test/             # node:test files mirroring src/ structure
+seeds/            # shipped skill/agent seed assets
+scripts/          # repo-level helper scripts
+docs/             # human-facing documentation
+```
+
+## Runtime and toolchain
+
+- Bun `>= 1.3.14` is the installed CLI/MCP runtime and the canonical CI verification path. It is also the only supported storage runtime (`bun:sqlite`).
+- Node.js `>= 22` is development/build/test tooling for TypeScript, `node:test`, and selected helper scripts.
+- TypeScript is ESM/NodeNext and strict, with `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`. Prefer explicit `undefined` over loose optional properties.
+- Tests use the built-in `node:test` runner with `node:assert/strict`, not Jest/Vitest.
+
+Install dependencies with `bun install --frozen-lockfile` when reproducing CI. When `package.json` dependency specifiers change, refresh and review `bun.lock` intentionally. Use `bun run check:bun-lock` to detect drift without mutating `node_modules`.
+
+## Verification order
+
+CI runs the verification chain in this order:
+
+```bash
+bun install --frozen-lockfile
+bun run check:bun-lock
+bun run verify:typecheck
+bun run verify:test
+bun run verify:test:bun-storage
+bun run verify:bun-sqlite
+bun run verify:package       # which is bun run package:bun:evidence
+bun run package:bun:evidence -- --require-pass
+```
+
+The full chain is wrapped in `bun run verify`. For release-readiness, the package evidence run must pass explicitly with `--require-pass`.
+
+`bun run verify:bun-sqlite` is the SQLite runtime release gate. It copies the source migrations into a temporary directory, applies them against a temporary database, and checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup.
+
+## Product boundaries
+
+VGXNESS is a local-first CLI/MCP control plane. The same domain services should back CLI, TUI, and MCP. Avoid reimplementing workflow, setup, or storage rules in only one surface.
+
+The configurator/setup plane (rendering/installing provider config) is separate from the runtime control plane (executing SDD phases, recording runs, gating approvals). They are wired by services, not by side effects.
+
+## Safety conventions
+
+These rules are non-negotiable. The harness is loaded with capability; do not remove these guards.
+
+- Read-only/preview commands must stay non-mutating. Setup plans, MCP setup previews, OpenCode previews, workflow previews, and status views must not write provider config or call providers.
+- Provider config writes require explicit consent (`--yes` or equivalent confirmed flow) plus backup/rollback behavior.
+- Do not create or write `openspec/`. SDD artifacts are stored through the local SQLite artifact service under canonical topic keys `sdd/{change}/{phase}`.
+- Human acceptance is distinct from artifact presence. Do not infer acceptance from generated content or saved drafts. The runtime rejects `acceptedBy.type !== 'human'`.
+- Workspace boundary denials cannot be relaxed by agent or subagent overrides. The policy evaluator uses `realpathSync` to defeat symlink escapes.
+- Secrets and external directory access deny by default. Redaction helpers in `src/code/reporting/redaction.ts` and `src/export/redaction.ts` are the only place secret-shaped values should be stripped.
+
+## Style
+
+- TypeScript strict, ESM/NodeNext, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`.
+- Prefer explicit `undefined` over loose optional properties. Use the existing `MemoryResult<T>` / `MemoryResult<...>` style for fallible operations instead of throwing across module boundaries.
+- Domain entities live in their module's `schema.ts`. Tool-facing payloads live in `src/mcp/schema.ts` (or a sibling) and are validated with `zod` before dispatch.
+- Tests are colocated by module under `test/`. Use `node:test` and `node:assert/strict`. Each test file should set up its own `MemoryDatabase` (see existing files for the pattern).
+- Public CLI/setup language is English unless existing docs explicitly say otherwise.
+
+## Doc-sync discipline
+
+The docs are the user-facing contract. When the code drifts, the docs must catch up — not the other way around.
+
+- When you add, rename, or remove an MCP tool, update `SUPPORTED_VGX_MCP_TOOL_NAMES` in `src/mcp/schema.ts` and the table in [MCP tools](./mcp.md). They must stay in sync.
+- When you add a new CLI command, document it in [CLI reference](./cli.md).
+- When you change a permission category, default, or phase mode, update [Safety model](./safety.md).
+- When you add a migration, append it to the table in [Storage](./storage.md).
+- When you add or change a provider, update [Providers](./providers.md) and the [Code runtime](./code-runtime.md) tool list.
+
+## Pull request process
+
+VGXNESS is shipped as a proprietary package. The npm publication step is a separate, explicit, human-approved process. PRs that change published artifacts must:
+
+1. Run `bun run verify` locally and confirm all steps pass.
+2. Include or update tests for any behavioral change.
+3. Update docs that reference the changed surface.
+4. Not change the publication path. `npm publish`, `bun publish`, registry dry-runs, provenance upload, release creation, and dist-tag mutation are not part of normal PR flow.
+5. Not change `engines.bun` or remove the `bin`/`files` whitelist without a separate, documented decision.
+
+PRs that touch safety gates, permission categories, default policies, the run lifecycle, or the SDD acceptance gate are reviewed by a maintainer who can answer "does this still match the safety model?" without consulting the diff. If you are unsure, open the PR as a draft and ask.
+
+## Commit conventions
+
+- Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`, `build:`, `ci:`).
+- No `Co-Authored-By` lines for AI assistants. Do not add AI attribution to commits.
+- One logical change per commit. Squash fixups locally before pushing.
+
+## AI assistants in this repo
+
+`AGENTS.md` at the repository root carries the working instructions for AI assistants. The two non-negotiables are:
+
+- Do not write to `openspec/`.
+- Do not infer SDD acceptance from generated content. The runtime will reject it, but the rejection costs a run.