Improve context-store setup and cleanup UX

docs/cli.md

@@ -8,7 +8,7 @@ The OpenSpec CLI (`openspec`) provides terminal commands for project setup, vali
 |----------|----------|---------|
 | **Setup** | `init`, `update` | Initialize and update OpenSpec in your project |
 | **Workspaces (beta)** | `workspace setup`, `workspace list`, `workspace ls`, `workspace link`, `workspace relink`, `workspace doctor`, `workspace update`, `workspace open` | Set up local views over linked repos or folders |
-| **Shared context (beta)** | `context-store setup`, `context-store register`, `context-store list`, `context-store doctor`, `initiative create`, `initiative show`, `initiative list` | Manage local context-store registrations and durable initiative context |
+| **Shared context (beta)** | `context-store setup`, `context-store register`, `context-store unregister`, `context-store remove`, `context-store list`, `context-store doctor`, `initiative create`, `initiative show`, `initiative list` | Manage local context-store registrations and durable initiative context |
 | **Browsing** | `list`, `view`, `show` | Explore changes and specs |
 | **Validation** | `validate` | Check changes and specs for issues |
 | **Lifecycle** | `archive` | Finalize completed changes |
@@ -54,6 +54,10 @@ These commands support `--json` output for programmatic use by AI agents and scr
 | `openspec workspace relink` | Repair a linked path | `--json` for structured link output |
 | `openspec workspace doctor` | Check one workspace | `--json` for structured status output |
 | `openspec workspace update` | Refresh workspace-local guidance and agent skills | `--tools` selects agents; profile selects workflows |
+| `openspec context-store setup <id>` | Create a local context store | `--json` with explicit inputs for structured setup output |
+| `openspec context-store register <path>` | Register an existing context store | `--json` for structured registration output |
+| `openspec context-store unregister <id>` | Forget a local context-store registration | `--json` for structured cleanup output |
+| `openspec context-store remove <id>` | Delete a registered local context-store folder | `--yes --json` for non-interactive deletion |
 | `openspec context-store list` | Browse registered context stores | `--json` for structured registrations |
 | `openspec context-store doctor` | Check local store setup | `--json` for structured diagnostics |
 | `openspec initiative list` | Browse shared initiatives | `--json` for structured initiative records |
@@ -354,7 +358,9 @@ Context stores and initiatives are beta coordination surfaces. A context store i
 
 ### `openspec context-store setup`
 
-Create and register a local context store.
+Create and register a local context store. With no arguments in a terminal,
+OpenSpec guides the user through setup. Agents and scripts should pass explicit
+inputs and use `--json`.
 
 ```bash
 openspec context-store setup [id] [options]
@@ -374,6 +380,7 @@ When `--path` is omitted, setup creates the store under `getGlobalDataDir()/cont
 Examples:
 
 ```bash
+openspec context-store setup
 openspec context-store setup team-context
 openspec context-store setup team-context --path /repos/team-context --no-init-git
 openspec context-store setup team-context --json --no-init-git
@@ -394,6 +401,30 @@ openspec context-store register [path] [options]
 | `--id <id>` | Context store id; defaults to store metadata or folder name |
 | `--json` | Output JSON |
 
+### `openspec context-store unregister`
+
+Forget a local context-store registration without deleting files.
+
+```bash
+openspec context-store unregister <id> [--json]
+```
+
+Use this when a store was moved, cloned somewhere else, or should no longer be
+shown by OpenSpec on this machine.
+
+### `openspec context-store remove`
+
+Forget a local context-store registration and delete its local folder.
+
+```bash
+openspec context-store remove <id> [--yes] [--json]
+```
+
+`remove` shows the exact folder before deleting in an interactive terminal.
+Agents, scripts, and JSON callers must pass `--yes` to confirm deletion.
+OpenSpec refuses to delete a folder that does not contain matching
+context-store metadata.
+
 ### `openspec context-store list`
 
 List locally registered context stores.

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

@@ -19,6 +19,20 @@ 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.
 
+## Set Up Context Stores Non-Interactively
+
+Humans can run `openspec context-store setup` and answer prompts. Agents should
+pass the setup inputs explicitly.
+
+```bash
+openspec context-store setup team-context --no-init-git --json
+openspec context-store setup team-context --path /path/to/team-context --init-git --json
+```
+
+Use `context-store unregister <id> --json` to forget a local registration while
+leaving files alone. Use `context-store remove <id> --yes --json` only when the
+user explicitly asks to delete the local context-store folder.
+
 ## Create Initiatives In Context Stores
 
 Create shared coordination context in a context store.

docs/workspaces-beta/user-guide.md

@@ -6,12 +6,12 @@ manages the OpenSpec work.
 ## 1. Create The Shared Place
 
 ```bash
-openspec context-store setup team-context --init-git
+openspec context-store setup
 ```
 
-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.
+OpenSpec asks for the context store name, where to put it, and whether to
+initialize Git. Press Enter for the managed local data directory unless you
+want the store somewhere specific.
 
 ## 2. Ask Your Agent To Create The Initiative
 

openspec/initiatives/context-store-and-initiatives/tasks.md

@@ -187,13 +187,13 @@ Work item: `work-items/11-manual-beta-reality-pass/`
 
 Work item: `work-items/12-context-store-first-run-and-cleanup-ux/`
 
-- [ ] Decide and implement interactive no-argument `context-store setup`.
-- [ ] Define target-path safety behavior for managed defaults, explicit paths,
+- [x] Decide and implement interactive no-argument `context-store setup`.
+- [x] Define target-path safety behavior for managed defaults, explicit paths,
   Git repos, and non-empty directories.
-- [ ] Add local cleanup support for unregistering or removing a context store.
-- [ ] Make setup and cleanup output report store root, registry state, Git
-  state, created files, and next commands.
-- [ ] Update docs and tests for first-run setup and cleanup behavior.
+- [x] Add local cleanup support for unregistering or removing a context store.
+- [x] Make setup and cleanup output report the agreed human-facing summary and
+  exact JSON state without workflow `next_commands`.
+- [x] Update docs and tests for first-run setup and cleanup behavior.
 
 ## 13. Agent Handoff Output And Delivery Polish
 

openspec/initiatives/context-store-and-initiatives/work-items/12-context-store-first-run-and-cleanup-ux/evidence.md

@@ -21,3 +21,25 @@ Keep context-store first-run UX small and local:
 - never push, pull, commit, create remotes, or delete files implicitly;
 - keep JSON output explicit enough for agents to continue safely;
 - leave team sync policy to the later shared-coordination hardening work.
+
+## Implementation Result
+
+- `openspec context-store setup` now runs a guided setup in interactive
+  terminals when no id is provided.
+- Non-interactive and `--json` setup require explicit inputs and fail with a
+  structured setup-id diagnostic when the id is missing.
+- Explicit setup paths inside another Git repository are blocked
+  non-interactively and require explicit confirmation interactively.
+- `context-store unregister <id>` removes only the local registry entry.
+- `context-store remove <id>` removes the local registry entry and deletes the
+  local folder only after confirmation or `--yes`; it refuses to delete folders
+  without matching context-store metadata.
+- Human success output is intentionally compact; JSON output carries exact
+  registry, file, and Git state without `next_commands`.
+
+Verification:
+
+- `pnpm build`
+- `pnpm lint`
+- `pnpm vitest run test/commands/context-store.test.ts test/core/context-store/registry.test.ts`
+- `pnpm test`

openspec/initiatives/context-store-and-initiatives/work-items/12-context-store-first-run-and-cleanup-ux/plan.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Proposed from the manual beta reality pass.
+Implemented.
 
 This work item covers the context-store setup and cleanup gaps that were not
 fully captured by later docs, schema, or handoff work.
@@ -43,8 +43,8 @@ stores as normal local workflow.
 - Make the target store path explicit before creation.
 - Provide a supported local cleanup command for removing or unregistering a
   context store from this machine.
-- Explain the Git/stage/commit state after initializing a shared store, without
-  pushing, committing, or creating remotes automatically.
+- Keep Git setup limited to optional local initialization, without staging,
+  committing, pushing, creating remotes, or choosing team workflow.
 
 ## Non-Goals
 
@@ -55,6 +55,42 @@ stores as normal local workflow.
 
 ## UX Direction
 
+Locked decisions from the product pass:
+
+- `openspec context-store setup` with no arguments should start a guided setup
+  when run in an interactive terminal. Agents, scripts, CI, and `--json` callers
+  should pass the equivalent explicit inputs instead of relying on prompts.
+- The guided setup should ask only for values that map to existing setup flags:
+  context store id, context store path, and whether to initialize Git.
+- User-facing prompt copy should stay direct:
+  `Context store name`, `Where should this context store live?`,
+  `Initialize Git in this context store?`, then a final
+  `Create this context store?` confirmation after showing the resolved summary.
+- The default location should be the managed OpenSpec context-store directory,
+  not the current working directory. Users can still choose any explicit safe
+  local path; OpenSpec stores that machine-local path in the local registry, not
+  in shared context-store metadata.
+- Setup should be protective around risky paths: create missing paths, accept
+  empty directories, treat matching context-store metadata as idempotent, stop
+  on metadata/id conflicts, stop on files, and stop or explicitly warn before
+  using a non-empty unmarked directory or a path inside another Git repository.
+- Cleanup should expose two explicit intents: `context-store unregister <id>`
+  forgets the machine-local registry entry and leaves files alone, while
+  `context-store remove <id>` unregisters the store and deletes the local folder
+  only after showing the exact path and receiving confirmation.
+- Happy-path human output should stay small: show the context store id, its
+  location, and the next user-facing step. Do not show Git state, metadata
+  paths, registry paths, or created-file lists unless there is a warning,
+  failure, `--json`, or `context-store doctor` output.
+- JSON output should report exact resulting state, not workflow guidance. Include
+  ids, roots, metadata paths, registry state, Git facts, created/deleted files,
+  and warnings/errors where present, but do not include `next_commands`. Empty
+  `status: []` can be preserved where existing JSON compatibility needs it, but
+  new behavior should not rely on blank status arrays for meaning.
+- Git initialization is an optional local convenience only. When requested,
+  OpenSpec may run `git init`, but it must not stage, commit, push, create
+  remotes, create branches, or define team Git policy.
+
 Interactive setup should cover the minimum choices:
 
 ```text
@@ -75,14 +111,14 @@ openspec context-store unregister team-context
 openspec context-store remove team-context
 ```
 
-The exact command names are open, but the user intent must be explicit:
+The command names are explicit because the user intents are different:
 
 - forget this local registry entry only
 - delete this local context-store folder too
 
-If a Git-backed context store was initialized, setup output should say that the
-store now has uncommitted files and that the user or agent should review,
-stage, commit, and push according to their team's normal Git workflow.
+If Git initialization fails, setup should explain that the user can install Git
+or rerun setup without Git. Successful Git initialization stays out of the
+happy-path human output.
 
 ## Agent / JSON Contract
 
@@ -94,8 +130,6 @@ JSON setup output should report:
 - whether Git was initialized
 - whether files were created or already existed
 - local registry path or registry entry identity
-- next commands for listing, doctor, and initiative creation
-- advisory Git status summary when available
 
 JSON cleanup output should report:
 

openspec/initiatives/context-store-and-initiatives/work-items/12-context-store-first-run-and-cleanup-ux/tasks.md

@@ -1,24 +1,23 @@
 # Context Store First-Run And Cleanup UX Tasks
 
-- [ ] Decide exact no-argument `context-store setup` behavior for TTY,
+- [x] Decide exact no-argument `context-store setup` behavior for TTY,
       non-TTY, and `--json` invocations.
-- [ ] Design the interactive setup prompts for store id, target path, and Git
+- [x] Design the interactive setup prompts for store id, target path, and Git
       initialization.
-- [ ] Define target-path safety behavior for managed defaults, explicit paths,
+- [x] Define target-path safety behavior for managed defaults, explicit paths,
       paths inside existing Git repos, and non-empty directories.
-- [ ] Implement the interactive setup flow without changing deterministic
+- [x] Implement the interactive setup flow without changing deterministic
       non-interactive behavior.
-- [ ] Decide whether the cleanup surface is `unregister`, `remove`, or both.
-- [ ] Define cleanup semantics for "forget local registration" versus "delete
+- [x] Decide whether the cleanup surface is `unregister`, `remove`, or both.
+- [x] Define cleanup semantics for "forget local registration" versus "delete
       local files too".
-- [ ] Implement local registry cleanup with explicit confirmation before file
+- [x] Implement local registry cleanup with explicit confirmation before file
       deletion.
-- [ ] Add human and JSON output that reports store root, metadata path, registry
-      state, created files, and next commands.
-- [ ] Add setup guidance for initialized Git stores that explains uncommitted
-      shared files without auto-staging, committing, pushing, or creating a
-      remote.
-- [ ] Add focused tests for setup prompts, non-interactive failures, path
+- [x] Add human output that stays small and JSON output that reports exact setup
+      and cleanup state without `next_commands`.
+- [x] Keep Git initialization scoped to local `git init` with no auto-staging,
+      committing, pushing, remote creation, or team policy.
+- [x] Add focused tests for setup prompts, non-interactive failures, path
       safety, registry cleanup, and JSON output.
-- [ ] Update beta docs and agent playbook references for first-run setup and
+- [x] Update beta docs and agent playbook references for first-run setup and
       cleanup.