refactor(config): compose v1.1 runtime and JSONC configuration

.env.example

@@ -1,38 +1,48 @@
+# Persistent product configuration belongs in ~/.devspace/config.jsonc.
+# Environment values are useful for bootstrap, secrets, deployment overrides,
+# and compatibility with pre-v1.1 setups.
+
 HOST=127.0.0.1
 PORT=7676
+
+# Locate an alternate config.jsonc/auth.json directory.
+# DEVSPACE_CONFIG_DIR=/path/to/devspace-config
+
 # Owner password generated by `devspace init` in ~/.devspace/auth.json. Set this
 # only for non-interactive or fully env-driven deployments.
 # DEVSPACE_OAUTH_OWNER_TOKEN=change-me-to-a-long-random-secret
-# Optional OAuth tuning.
-# DEVSPACE_OAUTH_ACCESS_TOKEN_TTL_SECONDS=3600
-# DEVSPACE_OAUTH_REFRESH_TOKEN_TTL_SECONDS=2592000
-# DEVSPACE_OAUTH_SCOPES=devspace
-# DEVSPACE_OAUTH_ALLOWED_REDIRECT_HOSTS=chatgpt.com,localhost,127.0.0.1
-DEVSPACE_ALLOWED_ROOTS=/home/waishnav/personal,/home/waishnav/work
-# For temporary tunnels, prefer setting this per run. DevSpace derives the
-# inbound Host allowlist from this URL.
+
+# Common deployment overrides.
+# DEVSPACE_ALLOWED_ROOTS=/home/me/personal,/home/me/work
 # DEVSPACE_PUBLIC_BASE_URL=https://your-public-host.example.com
-# Advanced escape hatch. `*` disables Host header allowlist protection.
 # DEVSPACE_ALLOWED_HOSTS=localhost,127.0.0.1,your-public-host.example.com
-DEVSPACE_TOOL_MODE=full
-# off | changes | full. Defaults to changes.
-# changes creates one aggregate review widget via review_changes instead of per-tool iframes.
-DEVSPACE_WIDGETS=changes
-DEVSPACE_LOG_LEVEL=info
-DEVSPACE_LOG_FORMAT=json
-DEVSPACE_LOG_REQUESTS=1
-DEVSPACE_LOG_ASSETS=0
-DEVSPACE_LOG_TOOL_CALLS=1
-DEVSPACE_LOG_SHELL_COMMANDS=0
-# DEVSPACE_TRUST_PROXY=1
-# DEVSPACE_STATE_DIR=/home/waishnav/.local/share/devspace
-# DEVSPACE_WORKTREE_ROOT=/home/waishnav/.devspace/worktrees
-# Native-file download is opt-in. Files stream to a model-selected relative
-# path inside an already-open workspace without overwriting existing files.
+# DEVSPACE_STATE_DIR=/home/me/.local/share/devspace
+# DEVSPACE_WORKTREE_ROOT=/home/me/.devspace/worktrees
+
+# Legacy harness/presentation overrides. Prefer config.jsonc for persistent use.
+# DEVSPACE_TOOL_MODE=minimal
+# DEVSPACE_MINIMAL_TOOLS=1
+# DEVSPACE_WIDGETS=full
+
+# Optional feature overrides.
 # DEVSPACE_ARTIFACTS=1
 # DEVSPACE_ARTIFACT_MAX_FILE_BYTES=104857600
-# DEVSPACE_AUTO_LOAD_AGENTS_MD=1
-# Skills are enabled by default. Set DEVSPACE_SKILLS=0 to hide them.
 # DEVSPACE_SKILLS=0
-# DEVSPACE_AGENT_DIR=/home/waishnav/.codex
-# DEVSPACE_SKILL_PATHS=/home/waishnav/.codex/skills,/home/waishnav/.claude/skills
+# DEVSPACE_AGENT_DIR=/home/me/.codex
+# DEVSPACE_SKILL_PATHS=/home/me/.claude/skills,/home/me/company/skills
+# DEVSPACE_SUBAGENTS=1
+
+# OAuth policy overrides.
+# DEVSPACE_OAUTH_ACCESS_TOKEN_TTL_SECONDS=3600
+# DEVSPACE_OAUTH_REFRESH_TOKEN_TTL_SECONDS=2592000
+# DEVSPACE_OAUTH_SCOPES=devspace
+# DEVSPACE_OAUTH_ALLOWED_REDIRECT_HOSTS=chatgpt.com,localhost,127.0.0.1
+
+# Logging overrides.
+# DEVSPACE_LOG_LEVEL=info
+# DEVSPACE_LOG_FORMAT=json
+# DEVSPACE_LOG_REQUESTS=1
+# DEVSPACE_LOG_ASSETS=0
+# DEVSPACE_LOG_TOOL_CALLS=1
+# DEVSPACE_LOG_SHELL_COMMANDS=0
+# DEVSPACE_TRUST_PROXY=1

AGENTS.md

@@ -26,7 +26,8 @@ These ideas should stay true as the project evolves:
 - **Allowed root** — a configured filesystem boundary within which a workspace may be opened. It is not itself necessarily a workspace.
 - **Checkout mode** — operating on an existing checkout supplied by the user.
 - **Worktree mode** — operating in an isolated Git worktree.
-- **Tool surface** — the tools exposed by a configured mode, such as minimal, full, or Codex-compatible.
+- **Coding harness** — the model-facing coding tool contract. DevSpace currently composes a Claude Code-style harness or a Codex-style harness.
+- **Presentation profile** — the host-rendered UI/review behavior: inline tool UI, aggregate change review, or off.
 - **Process session** — a long-running command tracked for later input, output, or termination.
 - **Instruction file** — an `AGENTS.md` or `CLAUDE.md` discovered while navigating a workspace.
 - **Subagent** — a bounded model invocation delegated and coordinated by the host.
@@ -62,8 +63,8 @@ Determine how the user will consume the change and verify that path. Behavior ma
 - a fresh process and a server or host that needs restarting;
 - checkout mode and worktree mode;
 - Linux, macOS, and Windows Bash environments;
-- minimal, full, and Codex-compatible tool surfaces;
-- widgets enabled, disabled, or limited to change review.
+- Claude Code shell-inspection, Claude Code dedicated-inspection, and Codex harnesses;
+- inline, change-review, and off presentation profiles.
 
 State clearly when only a narrower proxy was verified. For model-facing schemas, inspect what the host receives. For UI and artifacts, inspect the rendered result rather than inferring success from the producing command.
 
@@ -115,4 +116,4 @@ Start at the boundary named by the problem and follow the data. Keep policy in D
 - Preserve host and provider data unless DevSpace has a concrete reason to normalize it.
 - Add compatibility behavior only for an identified consumer with a real upgrade path.
 - Reuse glossary terms in schemas, types, documentation, and errors.
-- Keep the execution layer small, reliable, and unsurprising.
+- Keep the execution layer small, reliable, and unsurprising.

docs/chatgpt-coding-workflow.md

@@ -148,45 +148,56 @@ configuration. The bundled `subagents` skill teaches the minimal
 comes from `open_workspace`; `devspace agents ls` lists existing subagent
 sessions for that workspace.
 
-## Tool Names
+## Coding Harness
 
-DevSpace exposes these tool names:
+The default `claude-code` harness with `inspection: "shell"` exposes:
 
 - `open_workspace`
 - `read`
 - `write`
 - `edit`
 - `bash`
 
-By default, DevSpace also runs in `DEVSPACE_TOOL_MODE=minimal`, so dedicated
-`grep`, `glob`, and `ls` tools are hidden. Use `bash` with command-line tools
-such as `rg`, `find`, and `ls` for search and directory inspection.
+Dedicated `grep`, `glob`, and `ls` tools are hidden in that configuration. Use
+`bash` with command-line tools such as `rg`, `find`, and `ls` for search and
+directory inspection.
 
-Use `DEVSPACE_TOOL_MODE=full` to restore dedicated search and directory tools.
+Set `harness.inspection` to `"dedicated"` in `~/.devspace/config.jsonc` to expose
+the dedicated inspection tools.
 
-The experimental Codex-style surface is enabled with
-`DEVSPACE_TOOL_MODE=codex`. It exposes:
+The Codex harness is selected with:
+
+```jsonc
+{
+  "version": 1,
+  "harness": { "kind": "codex" }
+}
+```
+
+It exposes:
 
 - `open_workspace`
 - `read`
 - `apply_patch`
 - `exec_command`
 - `write_stdin`
 
-In this mode, `write`, `edit`, `bash`, `grep`, `glob`, and `ls` are not
+In this harness, `write`, `edit`, `bash`, `grep`, `glob`, and `ls` are not
 registered. `exec_command` returns a process session ID when a command is still
 running after its yield window. Use `write_stdin` to poll it, send input, resize
 a PTY, or send Ctrl-C. Set `tty: true` only for commands that need a terminal.
 
-## Show Changes
+`DEVSPACE_TOOL_MODE=minimal|full|codex` remains a compatibility override for
+older deployments.
 
-By default, `DEVSPACE_WIDGETS=full`.
+## Show Changes
 
-In that mode, DevSpace attaches widget UI to the exposed workspace, file, edit,
-and shell tools. The aggregate `show_changes` tool is not exposed by default.
+By default, `presentation.mode` is `"inline"`, which attaches widget UI to the
+normal exposed tools without registering the aggregate review tool.
 
-Use `DEVSPACE_WIDGETS=off` to disable widget UI, or `DEVSPACE_WIDGETS=changes`
-to expose the aggregate show-changes flow.
+Use `presentation.mode: "off"` to disable widget UI, or
+`presentation.mode: "change-review"` to expose the aggregate `show_changes`
+flow. `DEVSPACE_WIDGETS=off|changes|full` remains a compatibility override.
 
 When `show_changes` is exposed, call it exactly once after the final file
 modification in any turn that changes files. It shows the combined changes for