docs(init): guide local harness setup

Author: Waishnav

README.md

@@ -66,26 +66,28 @@ Install the DevSpace CLI:
 npm install -g @waishnav/devspace
 ```
 
-Then initialize and start the server:
+Then initialize DevSpace:
 
 ```bash
 devspace init
-devspace serve
 ```
 
 Or run it without a global install:
 
 ```bash
 npx @waishnav/devspace init
-npx @waishnav/devspace serve
 ```
 
 During setup, DevSpace asks for:
 
-- the local project folders ChatGPT is allowed to open through DevSpace
+- the local project folders DevSpace is allowed to open
 - the local port, usually `7676`
-- your public HTTPS base URL from Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel, or
-  another reverse proxy
+- whether a remote MCP host and/or local coding harness will use DevSpace
+- which subagent providers DevSpace may launch
+
+If a remote MCP host will connect, setup also asks for your public HTTPS base
+URL from Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel, or another reverse
+proxy. Local-harness-only setups do not need a tunnel or public URL.
 
 Use the public origin without `/mcp` during setup:
 
@@ -94,6 +96,9 @@ https://your-tunnel-host.example.com
 ```
 
 You will configure your MCP client with the public `/mcp` URL after setup.
+Run `devspace serve` when using the MCP server. For a local coding harness,
+setup prints a `skills` command that installs DevSpace's Subagents skill into
+the harnesses you choose; DevSpace does not write into their skill directories.
 
 When the client connects, DevSpace opens an Owner password approval page. Enter
 the Owner password printed by `devspace init`. It is also stored in:

docs/chatgpt-coding-workflow.md

@@ -116,7 +116,7 @@ DevSpace discovers standard Agent Skills from:
 
 It also keeps compatibility with:
 
-- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
+- the bundled `subagent-delegation` skill when Subagents are enabled, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
@@ -140,13 +140,13 @@ Skill paths may be outside the workspace. DevSpace only permits reading:
 - advertised `SKILL.md` files
 - files under a skill directory after that skill's `SKILL.md` has been read
 
-Set `DEVSPACE_SKILLS=0` to hide skills from workspace output. Set
-`DEVSPACE_SUBAGENTS=1` to expose the experimental subagent catalog and
-`subagent-delegation` skill. That skill teaches the minimal
-`devspace agents ls`, `devspace agents run`, `devspace agents continue`, and
-`devspace agents show`
-workflow. The catalog comes from `open_workspace`; `devspace agents ls` lists
-existing subagent sessions for that workspace.
+Set `DEVSPACE_SKILLS=0` to hide skills from workspace output. Enable Subagents
+and choose providers through `devspace init` or the persisted provider
+configuration. The bundled `subagent-delegation` skill teaches the minimal
+`devspace agents targets`, `devspace agents ls`, `devspace agents run`,
+`devspace agents continue`, and `devspace agents show` workflow. The catalog
+comes from `open_workspace`; `devspace agents ls` lists existing subagent
+sessions for that workspace.
 
 ## Tool Names
 

docs/configuration.md

@@ -136,7 +136,7 @@ DevSpace discovers standard Agent Skills from:
 
 It also keeps compatibility with:
 
-- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
+- the bundled `subagent-delegation` skill when Subagents are enabled, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
@@ -187,8 +187,16 @@ providers and their profiles are omitted from this model-facing catalog. `devspa
 lists existing subagent sessions for the current workspace, scoped by the
 workspace environment injected into shell commands. The `subagent-delegation`
 skill teaches the model to use only the minimal `devspace agents ls`,
-`devspace agents run`, `devspace agents continue`, and `devspace agents show`
-workflow.
+`devspace agents targets`, `devspace agents run`, `devspace agents continue`,
+and `devspace agents show` workflow.
+
+For Codex, Claude Code, OpenCode, Pi, or another supported local harness, use
+the Skills CLI to install the same skill. DevSpace setup prints this command but
+does not run it or write into harness directories:
+
+```bash
+npx skills add Waishnav/devspace --skill subagent-delegation --global
+```
 
 Starter profile templates are available under `examples/agents/`. Copy or adapt
 them into one of the active profile directories before use.

docs/gotchas.md

@@ -216,21 +216,31 @@ DevSpace looks in standard Agent Skills locations:
 
 It also checks compatibility and custom paths:
 
-- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
+- the bundled `subagent-delegation` skill when Subagents are enabled, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
-When `DEVSPACE_SUBAGENTS=1`, DevSpace loads agent profiles from
+When Subagents are enabled, DevSpace loads agent profiles from
 `~/.devspace/agents/*.md` and project `.devspace/agents/*.md`, then exposes a
 compact profile catalog through `open_workspace`. The bundled
 `subagent-delegation` skill keeps the model-facing workflow to
-`devspace agents ls`, `devspace agents run`, `devspace agents continue`, and
-`devspace agents show`.
+`devspace agents targets`, `devspace agents ls`, `devspace agents run`,
+`devspace agents continue`, and `devspace agents show`.
 Those commands automatically manage the internal local agent daemon; `devspace
 serve` is not a prerequisite.
 `devspace agents ls` lists existing subagent sessions, not profile
 definitions.
 
+For a local coding harness, run the installation command printed by
+`devspace init`:
+
+```bash
+npx skills add Waishnav/devspace --skill subagent-delegation --global
+```
+
+The Skills CLI handles harness discovery and installation. DevSpace setup does
+not copy files into harness skill directories.
+
 Packaged agent profile examples under `examples/agents/` are starter templates.
 Copy or adapt them into one of the active profile directories before use.
 

docs/setup.md

@@ -1,18 +1,20 @@
 # Setup Guide
 
-This guide is for users who want ChatGPT or another MCP host to work in local
-projects through DevSpace.
+This guide covers both remote MCP hosts and local coding harnesses using
+DevSpace in local projects.
 
 ## Requirements
 
 - Node `>=22.19 <27`
 - npm
 - Git
 - Bash, including Git Bash or WSL on Windows
-- a public HTTPS URL that forwards to the local DevSpace server
+- a public HTTPS URL that forwards to the local DevSpace server, only when a
+  remote MCP host will connect
 
-DevSpace does not create the public tunnel for you. Use Cloudflare Tunnel,
-ngrok, Pinggy, Tailscale Funnel, or your own HTTPS reverse proxy.
+DevSpace does not create the public tunnel for you. Remote MCP users can use
+Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel, or their own HTTPS reverse
+proxy.
 
 ## Install And Configure
 
@@ -53,7 +55,26 @@ The local MCP URL is:
 http://127.0.0.1:7676/mcp
 ```
 
-### Public Base URL
+### Usage And Subagents
+
+Setup asks independently whether a remote MCP host will connect and whether a
+local coding harness will use DevSpace subagents. It then detects the supported
+providers and asks which ones DevSpace may launch. These choices are persisted
+as provider objects under `subagents` in `~/.devspace/config.json`.
+
+For a local harness, setup prints this command instead of modifying harness
+directories itself:
+
+```bash
+npx skills add Waishnav/devspace --skill subagent-delegation --global
+```
+
+The Skills CLI asks which installed harnesses should receive the skill. The
+skill uses `devspace agents targets`, `run`, `continue`, `show`, and `ls`; these
+commands start DevSpace's local agent daemon as needed and do not require
+`devspace serve`.
+
+### Public Base URL For Remote MCP
 
 Start your tunnel or reverse proxy before entering this value. Point the tunnel
 at:
@@ -74,6 +95,9 @@ Configure the MCP client with the full MCP endpoint:
 https://your-tunnel-host.example.com/mcp
 ```
 
+Skip remote MCP access during setup for a local-harness-only configuration; no
+public URL is required.
+
 ## Start The Server
 
 Run:

skills/subagent-delegation/SKILL.md

@@ -17,12 +17,17 @@ being used.
 Use only these commands for normal delegation:
 
 ```bash
+devspace agents targets
 devspace agents ls
 devspace agents run <profile-or-provider> "<prompt>"
 devspace agents continue <id> "<prompt>"
 devspace agents show <id>
 ```
 
+`targets` shows the providers and profiles usable from the current workspace.
+Use it when this skill is installed directly in a local coding harness. An MCP
+host may already have received the same compact catalog from `open_workspace`.
+
 `ls` shows existing subagent sessions for the current workspace. DevSpace scopes
 it automatically from the shell environment injected by the workspace tool.
 Use the returned logical `agt_...` ID with `continue`; provider session IDs and
@@ -60,9 +65,9 @@ DevSpace agent integration.
 ## Choosing a profile
 
 Choose profiles from the compact subagent profile catalog returned by
-`open_workspace`. Use the profile name with `devspace agents run`. If no
-profile fits and delegation is still appropriate, use a built-in provider name
-from `open_workspace`.
+`open_workspace` or `devspace agents targets`. Use the profile name with
+`devspace agents run`. If no profile fits and delegation is still appropriate,
+use a provider listed by the same catalog.
 
 Profiles may declare a model and optional effort level. To override the
 configured/default provider model or effort level for a run, pass `--model`