diff --git a/README.md b/README.md
index 922243f..eff4a2f 100644
--- a/README.md
+++ b/README.md
@@ -177,9 +177,13 @@ lore issues --has-due                 # Only issues with due dates
 lore issues -p group/repo            # Filter by project
 lore issues --sort created --asc     # Sort by created date, ascending
 lore issues -o                        # Open first result in browser
+
+# Field selection (robot mode)
+lore -J issues --fields minimal       # Compact: iid, title, state, updated_at_iso
+lore -J issues --fields iid,title,labels,state  # Custom fields
 ```
 
-When listing, output includes: IID, title, state, author, assignee, labels, and update time.
+When listing, output includes: IID, title, state, author, assignee, labels, and update time. In robot mode, the `--fields` flag controls which fields appear in the JSON response.
 
 When showing a single issue (e.g., `lore issues 123`), output includes: title, description, state, author, assignees, labels, milestone, due date, web URL, and threaded discussions.
 
@@ -220,6 +224,10 @@ lore mrs --since 7d                  # Updated in last 7 days
 lore mrs -p group/repo               # Filter by project
 lore mrs --sort created --asc        # Sort by created date, ascending
 lore mrs -o                           # Open first result in browser
+
+# Field selection (robot mode)
+lore -J mrs --fields minimal          # Compact: iid, title, state, updated_at_iso
+lore -J mrs --fields iid,title,draft,target_branch  # Custom fields
 ```
 
 When listing, output includes: IID, title (with [DRAFT] prefix if applicable), state, author, assignee, labels, and update time.
@@ -412,7 +420,7 @@ lore version
 
 ## Robot Mode
 
-Machine-readable JSON output for scripting and AI agent consumption.
+Machine-readable JSON output for scripting and AI agent consumption. All responses use compact (single-line) JSON with a uniform envelope and timing metadata.
 
 ### Activation
 
@@ -432,18 +440,51 @@ lore issues -n 5 | jq .
 
 ### Response Format
 
-All commands return consistent JSON:
+All commands return a consistent JSON envelope to stdout:
 
 ```json
-{"ok": true, "data": {...}, "meta": {...}}
+{"ok":true,"data":{...},"meta":{"elapsed_ms":42}}
 ```
 
-Errors return structured JSON to stderr:
+Every response includes `meta.elapsed_ms` (wall-clock milliseconds for the command).
+
+Errors return structured JSON to stderr with machine-actionable recovery steps:
 
 ```json
-{"error": {"code": "CONFIG_NOT_FOUND", "message": "...", "suggestion": "Run 'lore init'"}}
+{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'","actions":["lore init"]}}
 ```
 
+The `actions` array contains executable shell commands an agent can run to recover from the error. It is omitted when empty (e.g., for generic I/O errors).
+
+### Field Selection
+
+The `--fields` flag on `issues` and `mrs` list commands controls which fields appear in the JSON response, reducing token usage for AI agent workflows:
+
+```bash
+# Minimal preset (~60% fewer tokens)
+lore -J issues --fields minimal
+
+# Custom field list
+lore -J issues --fields iid,title,state,labels,updated_at_iso
+
+# Available presets
+#   minimal: iid, title, state, updated_at_iso
+```
+
+Valid fields for issues: `iid`, `title`, `state`, `author_username`, `labels`, `assignees`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`
+
+Valid fields for MRs: `iid`, `title`, `state`, `author_username`, `labels`, `draft`, `target_branch`, `source_branch`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `reviewers`
+
+### Agent Self-Discovery
+
+The `robot-docs` command provides a complete machine-readable manifest including response schemas for every command:
+
+```bash
+lore robot-docs | jq '.data.commands.issues.response_schema'
+```
+
+Each command entry includes `response_schema` describing the shape of its JSON response, `fields_presets` for commands supporting `--fields`, and copy-paste `example` invocations.
+
 ### Exit Codes
 
 | Code | Meaning |
@@ -467,6 +508,7 @@ Errors return structured JSON to stderr:
 | 16 | Embedding failed |
 | 17 | Not found (entity does not exist) |
 | 18 | Ambiguous match (use `-p` to specify project) |
+| 19 | Health check failed |
 | 20 | Config not found |
 
 ## Configuration Precedence