feat: document workspace remove command

AGENTS.md

@@ -362,6 +362,45 @@ tempDir := t.TempDir()  // Automatic cleanup
 sourcesDir := t.TempDir()
 ```
 
+## Documentation Standards
+
+### Markdown Best Practices
+
+All markdown files (*.md) in this repository must follow these standards:
+
+**Fenced Code Blocks:**
+- **ALWAYS** include a language tag in fenced code blocks
+- Use the appropriate language identifier (`bash`, `go`, `json`, `yaml`, `text`, etc.)
+- For output examples or plain text content, use `text` as the language tag
+- This ensures markdown linters (markdownlint MD040) pass and improves syntax highlighting
+
+**Examples:**
+
+````markdown
+<!-- CORRECT: Language tag specified -->
+```bash
+make build
+```
+
+```text
+Error: workspace not found: invalid-id
+Use 'workspace list' to see available workspaces
+```
+
+<!-- INCORRECT: Missing language tag -->
+```
+make build
+```
+````
+
+**Common Language Tags:**
+- `bash` - Shell commands and scripts
+- `go` - Go source code
+- `json` - JSON data structures
+- `yaml` - YAML configuration files
+- `text` - Plain text output, error messages, or generic content
+- `markdown` - Markdown examples
+
 ## Copyright Headers
 
 All source files must include Apache License 2.0 copyright headers with Red Hat copyright. Use the `/copyright-headers` skill to add or update headers automatically. The current year is 2026.

README.md

@@ -198,3 +198,63 @@ kortex-cli list -o json
 - When no workspaces are registered, the command displays "No workspaces registered"
 - The JSON output format is useful for scripting and automation
 - All paths are displayed as absolute paths for consistency
+
+### `workspace remove` - Remove a Workspace
+
+Removes a registered workspace by its ID. Also available as the shorter alias `remove`.
+
+#### Usage
+
+```bash
+kortex-cli workspace remove ID [flags]
+kortex-cli remove ID [flags]
+```
+
+#### Arguments
+
+- `ID` - The unique identifier of the workspace to remove (required)
+
+#### Flags
+
+- `--storage <path>` - Storage directory for kortex-cli data (default: `$HOME/.kortex-cli`)
+
+#### Examples
+
+**Remove a workspace by ID:**
+```bash
+kortex-cli workspace remove a1b2c3d4e5f6...
+```
+Output: `a1b2c3d4e5f6...` (ID of removed workspace)
+
+**Use the short alias:**
+```bash
+kortex-cli remove a1b2c3d4e5f6...
+```
+
+**View workspace IDs before removing:**
+```bash
+# First, list all workspaces to find the ID
+kortex-cli list
+
+# Then remove the desired workspace
+kortex-cli remove a1b2c3d4e5f6...
+```
+
+#### Error Handling
+
+**Workspace not found:**
+```bash
+kortex-cli remove invalid-id
+```
+Output:
+```text
+Error: workspace not found: invalid-id
+Use 'workspace list' to see available workspaces
+```
+
+#### Notes
+
+- The workspace ID is required and can be obtained using the `workspace list` or `list` command
+- Removing a workspace only unregisters it from kortex-cli; it does not delete any files from the sources or configuration directories
+- If the workspace ID is not found, the command will fail with a helpful error message
+- Upon successful removal, the command outputs the ID of the removed workspace