[codex] Polish beta context workspace flow

docs/cli.md

@@ -194,7 +194,7 @@ openspec workspace setup [options]
 | `--name <name>` | Workspace name. Names must be kebab-case |
 | `--link <path>` | Link an existing repo or folder and infer the link name from the folder name |
 | `--link <name>=<path>` | Link an existing repo or folder with an explicit link name |
-| `--opener <id>` | Store a preferred opener during non-interactive setup: `codex`, `claude`, `github-copilot`, or `editor` |
+| `--opener <id>` | Store a preferred opener during non-interactive setup: `codex-cli`, `claude`, `github-copilot`, or `editor` |
 | `--tools <tools>` | Install workspace-local OpenSpec skills for agents. Use `all`, `none`, or comma-separated tool IDs |
 | `--no-interactive` | Disable prompts; requires `--name` and at least one `--link` |
 | `--json` | Output JSON; requires `--no-interactive` |
@@ -204,7 +204,7 @@ openspec workspace setup [options]
 ```bash
 openspec workspace setup
 openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
-openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex
+openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex-cli
 openspec workspace setup --no-interactive --name platform --link /repos/api --tools codex,claude
 openspec workspace setup --no-interactive --json --name checkout --link /repos/platform/apps/checkout
 ```
@@ -268,7 +268,7 @@ Check what one workspace can resolve on the current machine.
 openspec workspace doctor [options]
 ```
 
-Doctor shows the workspace location, planning path, linked repos or folders, missing paths, repo-local specs paths when present, and suggested fixes. It reports issues only; it does not repair them automatically.
+Doctor shows the workspace location, linked repos or folders, missing paths, repo-local specs paths when present, and suggested fixes. JSON output also includes the workspace planning path for compatibility. It reports issues only; it does not repair them automatically.
 
 Commands that need one workspace use the current workspace when run from inside a workspace folder or subdirectory. From elsewhere, pass `--workspace <name>`, select from the picker in an interactive terminal, or rely on the only known workspace when exactly one exists. In `--json` or `--no-interactive` mode, ambiguous selection fails with a structured status error and suggests `--workspace <name>`.
 
@@ -320,7 +320,7 @@ openspec workspace open [name] [options]
 | `--initiative <id>` | Open an initiative as a local workspace view. Accepts `<id>` or `<store>/<id>` |
 | `--store <id>` | Registered context store id for `--initiative` |
 | `--store-path <path>` | Existing local context store root for `--initiative` |
-| `--agent <tool>` | One-session agent override: `codex`, `claude`, or `github-copilot` |
+| `--agent <tool>` | One-session agent override: `codex-cli`, `claude`, or `github-copilot` |
 | `--editor` | Open the maintained VS Code workspace file as a normal editor workspace |
 | `--no-interactive` | Disable workspace and opener picker prompts |
 
@@ -330,7 +330,7 @@ openspec workspace open [name] [options]
 openspec workspace open
 openspec workspace open platform
 openspec workspace open platform --agent github-copilot
-openspec workspace open --agent codex
+openspec workspace open --agent codex-cli
 openspec workspace open --editor
 openspec workspace open --initiative billing-launch --store platform
 openspec workspace open --initiative platform/billing-launch
@@ -340,9 +340,9 @@ openspec workspace open --initiative platform/billing-launch
 
 When `--initiative` is used, OpenSpec prepares or selects a private local workspace view for that initiative. Registry-selected stores are stored by id; `--store-path` stores a runtime-local path selector because workspace views are private local state.
 
-OpenSpec maintains `<workspace-name>.code-workspace` at the workspace root for VS Code editor and GitHub Copilot-in-VS-Code opens. That file is machine-local and ignored by default with a specific `<workspace-name>.code-workspace` `.gitignore` entry, so user-authored `*.code-workspace` files remain eligible for tracking.
+OpenSpec maintains `<workspace-name>.code-workspace` at the workspace root for VS Code editor and GitHub Copilot-in-VS-Code opens. That file is machine-local workspace view state.
 
-The maintained VS Code workspace includes the coordination root as `.` plus valid linked repos or folders as additional roots. VS Code displays those entries as a multi-root workspace.
+The maintained VS Code workspace lists valid linked repos or folders first, then initiative context when attached, then the OpenSpec workspace files. VS Code displays those entries as a multi-root workspace.
 
 Root workspace open makes linked repos or folders visible for exploration and context. Implementation edits should start only after an explicit user request and a normal OpenSpec implementation workflow.
 
@@ -364,11 +364,13 @@ openspec context-store setup [id] [options]
 
 | Option | Description |
 |--------|-------------|
-| `--path <path>` | Context store folder path; defaults to `./<id>` |
+| `--path <path>` | Context store folder path; defaults to OpenSpec's managed local data directory |
 | `--init-git` | Initialize a Git repository in the context store |
 | `--no-init-git` | Do not initialize a Git repository |
 | `--json` | Output JSON |
 
+When `--path` is omitted, setup creates the store under `getGlobalDataDir()/context-stores/<id>`: `$XDG_DATA_HOME/openspec/context-stores/<id>` when `XDG_DATA_HOME` is set, or `~/.local/share/openspec/context-stores/<id>` on Unix-style fallbacks. Pass `--path` when you want the store in a visible clone or team-specific folder.
+
 Examples:
 
 ```bash

docs/concepts.md

@@ -145,7 +145,7 @@ openspec workspace setup
 
 # Automation-friendly setup
 openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
-openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex
+openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex-cli
 
 # See known workspaces from the local registry
 openspec workspace list
@@ -174,17 +174,17 @@ openspec workspace open --initiative billing-launch --store platform
 openspec workspace open --initiative billing-launch --store-path /repos/platform-context
 ```
 
-`workspace setup` always creates the workspace in the standard workspace location, records it in the local registry, shows the workspace location, and requires at least one linked repo or folder. Interactive setup asks for a preferred opener and can install OpenSpec skills for selected agents. Non-interactive setup stores one only when `--opener codex`, `--opener claude`, `--opener github-copilot`, or `--opener editor` is provided.
+`workspace setup` always creates the workspace in the standard workspace location, records it in the local registry, shows the workspace location, and requires at least one linked repo or folder. Interactive setup asks for a preferred opener and can install OpenSpec skills for selected agents. Non-interactive setup stores one only when `--opener codex-cli`, `--opener claude`, `--opener github-copilot`, or `--opener editor` is provided.
 
 Workspace skills are installed only in the workspace root. The active global profile selects which workflow skills are generated; `--tools` selects which agents receive them. Workspace setup and update do not create slash command files even when global delivery includes commands. Run `openspec workspace update` to refresh workspace-local guidance and add, refresh, or remove managed workspace-local skill directories without editing linked repos or folders.
 
-OpenSpec also maintains root workspace open files: an OpenSpec-managed guidance block in `AGENTS.md`, a machine-local `<workspace-name>.code-workspace` file for VS Code and GitHub Copilot-in-VS-Code opens, and a specific ignore entry for that maintained `.code-workspace` file. User-authored `*.code-workspace` files remain trackable because the ignore rule targets only the maintained file.
+OpenSpec also maintains root workspace open files: an OpenSpec-managed guidance block in `AGENTS.md` and a machine-local `<workspace-name>.code-workspace` file for VS Code and GitHub Copilot-in-VS-Code opens. A managed workspace is not a repo, so OpenSpec does not create a default workspace `.gitignore` or a default workspace-level `changes/` directory.
 
-The maintained VS Code workspace includes the coordination root as `.` plus valid linked repos or folders as additional roots. VS Code displays those entries as a multi-root workspace.
+The maintained VS Code workspace lists valid linked repos or folders first, then initiative context when attached, then the OpenSpec workspace files. VS Code displays those entries as a multi-root workspace.
 
 `workspace open` opens the linked working set with the stored preferred opener unless `--agent <tool>` or `--editor` is passed for that one session. Passing both opener overrides is an error. Root workspace open makes linked repos and folders visible for exploration and context; implementation starts after the user explicitly asks for implementation work.
 
-`workspace link` and `workspace relink` record existing folders only; they do not create, copy, move, initialize, or edit the linked repo or folder. After a successful link or relink, OpenSpec refreshes the managed guidance, VS Code workspace file, and ignore rule.
+`workspace link` and `workspace relink` record existing folders only; they do not create, copy, move, initialize, or edit the linked repo or folder. After a successful link or relink, OpenSpec refreshes the managed guidance and VS Code workspace file.
 
 Workspace commands that need one workspace can run from anywhere with `--workspace <name>`. If you run them inside a workspace folder or subdirectory, OpenSpec uses that current workspace. If several known workspaces are available and you do not pass `--workspace <name>`, human commands show a picker; `--json` and `--no-interactive` fail with a structured status error instead of prompting.
 

docs/workspaces-beta/agent-cli-playbook.md

@@ -0,0 +1,82 @@
+# OpenSpec CLI Playbook For Agents
+
+Beta note: workspace and initiative flows are usable, but still small. Prefer
+plain commands, clear paths, and short status reports.
+
+## Start By Resolving Context
+
+Use JSON when you need exact paths.
+
+```bash
+openspec context-store list --json
+openspec initiative list --json
+openspec initiative show <store>/<initiative> --json
+openspec workspace doctor --json
+```
+
+When the user is working from an opened workspace, treat the workspace as the
+local view. Use `workspace doctor --json` to read linked repos/folders and the
+selected initiative. Do not assume the current directory is the repo that should
+own implementation artifacts.
+
+## Create Initiatives In Context Stores
+
+Create shared coordination context in a context store.
+
+```bash
+openspec initiative create billing-launch --store team-context --title "Billing Launch" --summary "Get billing live without losing the plot."
+```
+
+Then edit the initiative files in the context store:
+
+- `requirements.md`
+- `design.md`
+- `decisions.md`
+- `questions.md`
+- `tasks.md`
+
+## Explore Or Propose From A Workspace
+
+When the user asks to explore or draft work from a workspace:
+
+1. Resolve the workspace with `openspec workspace doctor --json`.
+2. Resolve the initiative with `openspec initiative show <store>/<initiative> --json`.
+3. Inspect linked repos or folders and identify the likely owning repo.
+4. If ownership is ambiguous, ask the user which linked repo should own the
+   repo-local OpenSpec change.
+5. Run explore/propose workflow commands from the owning repo, not from the
+   workspace root.
+
+The workspace is the cockpit for the conversation. It is not the durable home
+for implementation plans.
+
+## Create Changes From The Owning Repo
+
+Repo-local changes belong in the repo that owns the work.
+
+```bash
+openspec new change add-billing-api --initiative team-context/billing-launch
+```
+
+Run this command with the owning repo as the current working directory. Do not
+ask the user to type it and do not run initiative-linked change creation from a
+workspace root. If you only know the workspace, resolve linked repo paths first.
+
+After creating a change, report the absolute paths of the created files and the
+initiative link you used.
+
+## Use Doctor Before Guessing
+
+```bash
+openspec workspace doctor --workspace billing-launch --json
+openspec context-store doctor --json
+```
+
+## Do Not Promise Yet
+
+- Automatic sync, pull, push, or conflict handling.
+- Cloning repos.
+- Creating branches, worktrees, or submodules.
+- Workspace apply, verify, or archive.
+- Progress dashboards.
+- Enforced edit boundaries.

docs/workspaces-beta/user-guide.md

@@ -0,0 +1,76 @@
+# Using OpenSpec With Your Coding Agent
+
+Beta note: this is the smallest useful path. You do the local setup. Your agent
+manages the OpenSpec work.
+
+## 1. Create The Shared Place
+
+```bash
+openspec context-store setup team-context --init-git
+```
+
+This creates a local context store. Add `--path <folder>` if you want it
+somewhere specific; otherwise OpenSpec keeps it in its managed local data
+directory.
+
+## 2. Ask Your Agent To Create The Initiative
+
+> Create an OpenSpec initiative called `billing-launch` in `team-context`. Keep
+> it short and useful.
+
+## 3. Open Your Local Workbench
+
+```bash
+openspec workspace open
+```
+
+Select the initiative from the picker. OpenSpec creates a local workspace view
+for it if you do not already have one. When creating a new view, it also asks
+which local repos or folders to include.
+
+The opened editor view shows linked repos and folders first, initiative context
+when attached, and a small `OpenSpec workspace` folder last with `AGENTS.md`,
+`workspace.yaml`, and the generated `.code-workspace` file.
+
+Use `openspec workspace open --initiative team-context/billing-launch --editor`
+when you want to skip the picker. Use `--agent codex-cli`, `--agent claude`, or
+`--agent github-copilot` instead of `--editor` when you want to open an agent
+directly.
+
+## 4. Check The Local Context
+
+Ask your agent to inspect the opened workspace before planning work:
+
+> Check this OpenSpec workspace. Resolve the selected initiative, list the
+> linked repos or folders, and tell me if anything important is missing before
+> we explore the work.
+
+If a repo or folder is missing, tell the agent which local path should be linked.
+OpenSpec does not clone anything.
+
+## 5. Explore Before Creating Artifacts
+
+Use the workspace as the place where the conversation happens:
+
+> Using initiative `team-context/billing-launch`, explore the work in this
+> workspace. Read the initiative context and linked repo context first. Do not
+> create a change yet; help me decide what should be proposed and where the
+> OpenSpec artifacts should live.
+
+## 6. Ask For A Draft When Ready
+
+When exploration has converged, ask the agent to create the right artifact in
+the right place:
+
+> Create a draft repo-local OpenSpec proposal for the owning linked repo and
+> link it to `team-context/billing-launch`. Resolve the workspace and initiative
+> context yourself, run the needed OpenSpec commands from the correct repo, and
+> report the files you created.
+
+## Tiny Caveat Box
+
+OpenSpec is not cloning, syncing, branching, or tracking progress dashboards in
+this beta flow. It gives you shared initiative context, a local workspace view,
+and repo-local plans tied back to the bigger mission. The workspace is where
+you and the agent work together; durable plan artifacts should live in the
+context store initiative or in the owning repo, not in the workspace root.