docs: update README for --fields, elapsed_ms, error actions, exit code 19

Documents the robot mode enhancements from the previous commits:

- Field selection (--fields flag and minimal preset) with examples
  and complete field lists for issues and MRs
- Updated response format section to show meta.elapsed_ms and compact
  single-line JSON
- Error actions array with recovery shell commands
- Agent self-discovery section explaining robot-docs response_schema
- Exit code 19 for health check failure added to the table

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Taylor Eernisse
2026-02-06 23:47:30 -05:00
parent b5f78e31a8
commit 3e7fa607d3

View File

@@ -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