@fatecannotbealtered-/jira-cli 1.0.6 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-06-06
+
+### Added
+
+- **Agent JSON envelope** — default JSON success and failure responses now share a stable envelope: `ok`, `schema_version`, `data`/`error`, and `meta.duration_ms`.
+- **Confirm-token write flow** — JSON write commands now support the non-interactive `--dry-run` → `--confirm <token>` flow. Dry-run responses include a change preview, `confirm_token`, and `expires_at`; execution validates that the token still matches the operation.
+- **Self-description commands** — added `context`, and expanded `reference` and `doctor` output for agent discovery and environment checks.
+- **Structured error taxonomy** — error envelopes now include stable `E_*` codes and `retryable` hints for automated retry decisions.
+
+### Changed
+
+- **JSON is the agent contract** — stdout now contains exactly one JSON document for normal command responses; human-readable output requires `--format text`.
+- **Error JSON moved to stdout** — machine-readable failures now use the same stdout channel and envelope shape as successes. Progress, prompts, warnings, and text-mode errors remain on stderr.
+- **Exit code semantics** — exit codes now follow the agent contract: `2` bad args, `3` not found, `4` auth/permission, `5` confirmation required, `6` conflict, `7` retryable transient failure, `8` timeout.
+- **Interactive login is text-only** — default JSON mode requires `jira-cli login --host <url> --token <pat>`; interactive login requires `--format text`.
+- **`doctor` output** — JSON output now reports a `checks` list with `check`, `status`, `message`, and `fix` fields instead of the old `authValid` shape.
+
+### Fixed
+
+- **JSON write safety** — confirmed JSON writes no longer fall through to stdin prompts after token validation.
+- **Stable confirmation hashing** — write-command confirm tokens include the full operation details and stable slice handling in tests.
+
 ## [1.0.6] - 2026-06-05
 
 ### Added
@@ -137,7 +159,8 @@ Initial release of jira-cli for Jira Data Center.
 - SKILL.md with JSON output schemas, error codes, exit codes, and complete flag reference.
 - GitHub PR template for contributors.
 
-[Unreleased]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.6...HEAD
+[Unreleased]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.6...v1.1.0
 [1.0.6]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.5...v1.0.6
 [1.0.5]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.4...v1.0.5
 [1.0.4]: https://github.com/fatecannotbealtered/jira-cli/compare/v1.0.3...v1.0.4

package/README.md

@@ -48,8 +48,8 @@ npm install -g @fatecannotbealtered-/jira-cli
 # Install CLI Skill (required) — copies into your agent-supported skills directory
 npx skills add fatecannotbealtered/jira-cli -y -g
 
-# Login and verify
-jira-cli login
+# Login and verify (interactive login is text mode)
+jira-cli --format text login
 jira-cli doctor
 ```
 
@@ -70,7 +70,7 @@ Download from [GitHub Releases](https://github.com/fatecannotbealtered/jira-cli/
 ```bash
 jira-cli update --check              # check latest GitHub Release
 jira-cli update                      # update a standalone binary
-jira-cli update --version v1.2.3     # install a specific release
+jira-cli update --version v1.1.0     # install a specific release
 ```
 
 `jira-cli update` verifies `checksums.txt` before replacing the current binary. If the CLI was installed through npm, the command will recommend the package-manager path instead:
@@ -88,7 +88,7 @@ jira-cli supports **Jira Data Center** (private deployments) with **Personal Acc
 ### Interactive login
 
 ```bash
-jira-cli login
+jira-cli --format text login
 # Jira host: https://jira.company.com
 # Personal Access Token (PAT): ****
 # ✔ Logged in as John Doe (johndoe)
@@ -110,7 +110,7 @@ Environment variables take precedence over the config file. This is the recommen
 ```bash
 export JIRA_HOST=https://jira.company.com
 export JIRA_TOKEN=<your-personal-access-token>
-jira-cli doctor   # verify authValid is true
+jira-cli doctor   # verify .data.config.auth_status is "valid"
 ```
 
 ### Generating a PAT
@@ -129,47 +129,47 @@ jira-cli issue get PROJ-123
 jira-cli issue list --project PROJ
 jira-cli issue list --project PROJ --status "In Progress" --assignee me
 
-# Create & Edit
-jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug
-jira-cli issue create --project PROJ --summary "Sized story" --field "Story Points=5"
-jira-cli issue edit PROJ-123 --priority High --assignee me
-jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
-jira-cli issue delete PROJ-123 --force          # --force skips confirmation prompt
-jira-cli issue delete PROJ-123 --dry-run   # preview delete (no confirmation prompt)
+# Create & Edit (direct human execution uses text mode; JSON automation uses dry-run/confirm)
+jira-cli --format text issue create --project PROJ --summary "Fix login bug" --type Bug
+jira-cli --format text issue create --project PROJ --summary "Sized story" --field "Story Points=5"
+jira-cli --format text issue edit PROJ-123 --priority High --assignee me
+jira-cli --format text issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
+jira-cli --format text issue delete PROJ-123 --force          # skips text-mode confirmation prompt
+jira-cli issue delete PROJ-123 --dry-run                      # preview delete and get confirm_token
 
 # Clone
-jira-cli issue clone PROJ-123
-jira-cli issue clone PROJ-123 --summary "New title" --with-links
+jira-cli --format text issue clone PROJ-123
+jira-cli --format text issue clone PROJ-123 --summary "New title" --with-links
 
 # Status
 jira-cli issue transitions PROJ-123          # List available transitions
-jira-cli issue transition PROJ-123 "Done"    # Status name required as argument
+jira-cli --format text issue transition PROJ-123 "Done"    # Status name required as argument
 
 # Bulk Transition
-jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3
-jira-cli issue bulk-transition "In Progress" --jql "sprint = 10 AND status = 'To Do'"
+jira-cli --format text issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3
+jira-cli --format text issue bulk-transition "In Progress" --jql "sprint = 10 AND status = 'To Do'"
 
 # Collaboration
-jira-cli issue assign PROJ-123 me               # Assign to current user
-jira-cli issue assign PROJ-123 johndoe          # Assign by username (DC uses name, not accountId)
-jira-cli issue watch PROJ-123
-jira-cli issue vote PROJ-123
+jira-cli --format text issue assign PROJ-123 me               # Assign to current user
+jira-cli --format text issue assign PROJ-123 johndoe          # Assign by username (DC uses name, not accountId)
+jira-cli --format text issue watch PROJ-123
+jira-cli --format text issue vote PROJ-123
 
 # Comments
-jira-cli issue comment add PROJ-123 --body "Fixed in PR #42"
+jira-cli --format text issue comment add PROJ-123 --body "Fixed in PR #42"
 jira-cli issue comment list PROJ-123
 
 # Worklogs
-jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging"
+jira-cli --format text issue worklog add PROJ-123 --time 2h --comment "Debugging"
 jira-cli issue worklog list PROJ-123
 
 # Links & Attachments
-jira-cli issue link PROJ-123 --to PROJ-456 --type "blocks"
-jira-cli issue attach PROJ-123 --file ./screenshot.png
+jira-cli --format text issue link PROJ-123 --to PROJ-456 --type "blocks"
+jira-cli --format text issue attach PROJ-123 --file ./screenshot.png
 jira-cli issue attachments PROJ-123                       # List attachments
 jira-cli issue attachments PROJ-123 --out ./downloads     # Download all attachments
 jira-cli issue attachments PROJ-123 --out ./downloads --id 4609477   # Download one by ID
-jira-cli issue remote-link PROJ-123 --url https://pr.url --title "PR #42"
+jira-cli --format text issue remote-link PROJ-123 --url https://pr.url --title "PR #42"
 ```
 
 ### Search (JQL)
@@ -186,9 +186,9 @@ jira-cli search "project = PROJ" --limit 100 --order-by updated
 ```bash
 jira-cli sprint list --board 42
 jira-cli sprint active --board 42
-jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14
-jira-cli sprint move --sprint 10 --issues PROJ-123,PROJ-124
-jira-cli sprint close --sprint 10
+jira-cli --format text sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14
+jira-cli --format text sprint move --sprint 10 --issues PROJ-123,PROJ-124
+jira-cli --format text sprint close --sprint 10
 jira-cli sprint close --sprint 10 --dry-run       # preview without closing
 ```
 
@@ -226,7 +226,7 @@ jira-cli --format raw filter run <filterId>
 
 `jira-cli` defaults to machine-readable JSON, so scripts and AI Agents can omit output flags. Use `--format json|text|raw` to choose the result format:
 
-- `json` is the default. Success JSON goes to stdout; error JSON goes to stderr.
+- `json` is the default. Success and error envelopes both go to stdout; logs, prompts, and warnings go to stderr.
 - `text` is for human-readable summaries, tables, colors, diff/log text, and prompts.
 - `raw` is for unwrapped raw command results where supported. Unsupported commands return an argument error instead of silently downgrading.
 
@@ -234,18 +234,18 @@ jira-cli --format raw filter run <filterId>
 
 `--compact` only affects JSON. `--fields` only works with JSON output. `--quiet` suppresses auxiliary text output only; it does not suppress JSON or raw main results.
 
-By default, issue and sprint data is returned in a **flat, token-efficient JSON format** (ideal for AI Agents):
+By default, issue and sprint data is returned in the envelope's `data` field as a **flat, token-efficient JSON format** (ideal for AI Agents):
 
 ```bash
 # Flat JSON (default) — minimal fields, low token cost
 jira-cli issue get PROJ-123
-jira-cli search "project = PROJ" | jq '.issues[].key'
+jira-cli search "project = PROJ" | jq '.data.issues[].key'
 
-# issue list returns a bare array; search wraps issues in pagination metadata
-# filter run with --fields also returns a bare trimmed array
-jira-cli issue list --project PROJ | jq '.[].key'
-jira-cli search "project = PROJ" | jq '.issues[].key'
-jira-cli filter run 12345 --fields key,summary | jq '.[].key'
+# issue list returns an array in .data; search wraps issues in pagination metadata under .data
+# filter run with --fields also returns a trimmed array in .data
+jira-cli issue list --project PROJ | jq '.data[].key'
+jira-cli search "project = PROJ" | jq '.data.issues[].key'
+jira-cli filter run 12345 --fields key,summary | jq '.data[].key'
 
 # Trim flat JSON output (issue get / issue list / sprint / filter run)
 jira-cli issue get PROJ-123 --fields key,summary,status,assignee
@@ -266,22 +266,36 @@ jira-cli --compact issue get PROJ-123
 jira-cli issue delete PROJ-123 --dry-run
 ```
 
+JSON-mode write commands use a two-step confirmation flow:
+
+```bash
+TOKEN=$(jira-cli issue create --project PROJ --summary "Fix login bug" --dry-run --compact | jq -r '.data.confirm_token')
+jira-cli issue create --project PROJ --summary "Fix login bug" --confirm "$TOKEN"
+```
+
 ### Verify connectivity (`doctor`)
 
-With the default JSON output, check the `authValid` field (exit code 3 on auth/config failure):
+With the default JSON output, check `data.config.auth_status` (exit code 4 on auth/config failure):
 
 ```bash
-jira-cli doctor | jq '.authValid'   # must be true
+jira-cli doctor | jq -e '.data.config.auth_status == "valid"'
 ```
 
-Error responses (stderr) include machine-readable error codes and actionable hints:
+Error responses use the same stdout envelope and include machine-readable error codes and retry hints:
 
 ```json
 {
-  "error": "Jira API error 404: Issue does not exist",
-  "statusCode": 404,
-  "errorCode": "NOT_FOUND",
-  "hint": "Verify the issue key exists and you have permission to view it"
+  "ok": false,
+  "schema_version": "1.0",
+  "error": {
+    "code": "E_NOT_FOUND",
+    "message": "Jira API error 404: Issue does not exist",
+    "details": {
+      "status_code": 404,
+      "hint": "Verify the resource key/ID exists and you have permission to view it"
+    },
+    "retryable": false
+  }
 }
 ```
 
@@ -321,6 +335,7 @@ Credentials stored at `~/.jira-cli/config.json` (permissions: 0600):
 | `--force` | Skip interactive confirmation prompts |
 | `--quiet` | Suppress auxiliary text output; does not suppress JSON/raw main results |
 | `--dry-run` | Show what would be done without executing (supported by write/update commands) |
+| `--confirm <token>` | Execute a JSON-mode write command using the token returned by `--dry-run` |
 
 ### Per-command flags
 
@@ -337,7 +352,7 @@ Credentials stored at `~/.jira-cli/config.json` (permissions: 0600):
 | Issue | Solution |
 |---|---|
 | npm install fails / curl not found | Ensure `curl` is on PATH (required by npm postinstall to download the binary) |
-| Config not found | Run `jira-cli login` or set `JIRA_HOST` and `JIRA_TOKEN` env vars |
+| Config not found | Run `jira-cli --format text login`, `jira-cli login --host <url> --token <pat>`, or set `JIRA_HOST` and `JIRA_TOKEN` env vars |
 | Authentication failed | Regenerate PAT in your Jira DC profile settings |
 | Permission denied | Check your PAT scope and project permissions |
 | Resource not found | Verify the issue key or project key exists |
@@ -348,7 +363,7 @@ Credentials stored at `~/.jira-cli/config.json` (permissions: 0600):
 
 - Credentials are stored locally at `~/.jira-cli/config.json` with `0600` file permissions (user-only readable)
 - Config directory is created with `0700` permissions
-- PAT input is hidden during `jira-cli login` (uses terminal secure input)
+- PAT input is hidden during `jira-cli --format text login` (uses terminal secure input)
 - All communication uses HTTPS (host must start with `https://`)
 - No credentials are logged or transmitted to third parties
 - Environment variables `JIRA_HOST` and `JIRA_TOKEN` take precedence over config file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fatecannotbealtered-/jira-cli",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Full-featured Jira Data Center CLI for humans and AI Agents — manage issues, sprints, boards, epics, projects, users, and filters from your terminal",
   "keywords": [
     "jira",

package/skills/jira-cli/SKILL.md

@@ -17,8 +17,8 @@ npm install -g @fatecannotbealtered-/jira-cli
 # Install CLI Skill (required) — copies into your agent-supported skills directory
 npx skills add fatecannotbealtered/jira-cli -y -g
 
-# Login and verify
-jira-cli login
+# Login and verify (interactive login is text mode)
+jira-cli --format text login
 jira-cli doctor
 ```
 
@@ -47,22 +47,30 @@ Before using any command, authenticate with a Jira DC instance. Follow these ste
 2. Ask the user for a **Personal Access Token (PAT)**. If they don't have one, guide them:
    "Log in to your Jira DC → click your profile avatar → Personal Access Tokens → Create token."
 3. Run `jira-cli login --host <URL> --token <PAT>` to save credentials.
-4. Run `jira-cli doctor` to verify connectivity. Check that `authValid` is `true` (exit code 3 on auth/config failure).
+4. Run `jira-cli doctor` to verify connectivity. Check that `.data.config.auth_status` is `"valid"` (exit code 4 on auth/config failure).
 
 **Important:** Credentials are saved locally at `~/.jira-cli/config.json`. Environment variables `JIRA_HOST` and `JIRA_TOKEN` override the config file — use them for CI or when the user prefers not to save credentials.
 
 **Do not add output flags for programmatic parsing.** JSON is the default. Use `--format text` only when the user wants human-readable tables or summaries.
 
-**Stdout vs stderr:** Success JSON is written to **stdout** by default; error JSON is written to **stderr**. Capture stdout for data; check exit code and stderr for failures.
+**Stdout vs stderr:** Success and error JSON envelopes are written to **stdout** by default. Progress, prompts, warnings, and text-mode errors are written to **stderr**. Capture stdout for data and error envelopes; use exit codes for control flow.
 
 ## Safety
 
-- **Do NOT use `--force` on destructive commands unless the user explicitly asks.** Commands like `issue delete` prompt for confirmation by default. Skipping confirmation with `--force` is irreversible.
-- **`issue delete --dry-run` skips confirmation** — dry-run is evaluated before the confirmation prompt.
+- **Do NOT use `--force` on destructive commands unless the user explicitly asks.** In text mode, commands like `issue delete` prompt for confirmation by default. Skipping confirmation with `--force` is irreversible.
+- **Use `--dry-run` before JSON write operations**, inspect `.data.preview`, then execute the same command with `--confirm <token>` from `.data.confirm_token`.
+- **`issue delete --dry-run` skips confirmation** — dry-run is evaluated before any text-mode confirmation prompt.
 - **Use `--dry-run` before write operations** to preview what will happen without executing. Example: `issue create --project PROJ --summary "test" --type Task --dry-run`.
 - **AI Agents can make mistakes.** Always confirm with the user before executing `issue delete`, `issue bulk-transition`, `sprint close`, or any operation that modifies multiple issues.
 - All write operations are recorded in `~/.jira-cli/audit/` for traceability.
 
+JSON write flow:
+
+```bash
+TOKEN=$(jira-cli issue create --project PROJ --summary "Fix login bug" --dry-run --compact | jq -r '.data.confirm_token')
+jira-cli issue create --project PROJ --summary "Fix login bug" --confirm "$TOKEN"
+```
+
 ## Issue Management
 
 ```bash
@@ -70,61 +78,62 @@ Before using any command, authenticate with a Jira DC instance. Follow these ste
 jira-cli issue get PROJ-123
 jira-cli issue get PROJ-123 --fields key,summary,status,assignee   # Output trimming (flat JSON)
 jira-cli --format raw issue get PROJ-123                            # Full Jira API response
-jira-cli issue list --project PROJ                                  # Returns bare array of flat issues
+jira-cli issue list --project PROJ                                  # Returns envelope with flat issue array in .data
 jira-cli issue list --project PROJ --fields key,summary,status      # Trimmed array
 
 # Create and edit
-jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug
-jira-cli issue create --project PROJ --summary "New feature" --type Story --assignee me --priority High
-jira-cli issue create --project PROJ --summary "Sized story" --type Story --field "Story Points=5"
-jira-cli issue edit PROJ-123 --summary "Updated summary" --priority Medium
-jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
-jira-cli issue delete PROJ-123 --force          # Skip confirmation prompt
-jira-cli issue delete PROJ-123 --dry-run        # Preview delete (no confirmation prompt)
+# For direct human execution, use --format text. For JSON automation, use dry-run/confirm.
+jira-cli --format text issue create --project PROJ --summary "Fix login bug" --type Bug
+jira-cli --format text issue create --project PROJ --summary "New feature" --type Story --assignee me --priority High
+jira-cli --format text issue create --project PROJ --summary "Sized story" --type Story --field "Story Points=5"
+jira-cli --format text issue edit PROJ-123 --summary "Updated summary" --priority Medium
+jira-cli --format text issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend"
+jira-cli --format text issue delete PROJ-123 --force          # Skip text-mode confirmation prompt
+jira-cli issue delete PROJ-123 --dry-run                      # Preview delete and get confirm_token
 
 # Clone an issue
-jira-cli issue clone PROJ-123                                # Clone with default summary
-jira-cli issue clone PROJ-123 --summary "New title"          # Clone with custom summary
-jira-cli issue clone PROJ-123 --with-links                   # Clone with issue links
+jira-cli --format text issue clone PROJ-123                                # Clone with default summary
+jira-cli --format text issue clone PROJ-123 --summary "New title"          # Clone with custom summary
+jira-cli --format text issue clone PROJ-123 --with-links                   # Clone with issue links
 
 # Status transitions
 jira-cli issue transitions PROJ-123                 # List available transitions
-jira-cli issue transition PROJ-123 "In Progress"    # Transition to status (name required)
-jira-cli issue transition PROJ-123 "Done"
+jira-cli --format text issue transition PROJ-123 "In Progress"    # Transition to status (name required)
+jira-cli --format text issue transition PROJ-123 "Done"
 
 # Bulk transition
-jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3
-jira-cli issue bulk-transition "In Progress" --jql "project = PROJ AND sprint = 10 AND status = 'To Do'"
+jira-cli --format text issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3
+jira-cli --format text issue bulk-transition "In Progress" --jql "project = PROJ AND sprint = 10 AND status = 'To Do'"
 
 # Assignment and watching
-jira-cli issue assign PROJ-123 me                   # Assign to current user
-jira-cli issue assign PROJ-123 johndoe              # Assign by username (DC uses name, not accountId)
-jira-cli issue unassign PROJ-123
-jira-cli issue watch PROJ-123
-jira-cli issue unwatch PROJ-123
+jira-cli --format text issue assign PROJ-123 me                   # Assign to current user
+jira-cli --format text issue assign PROJ-123 johndoe              # Assign by username (DC uses name, not accountId)
+jira-cli --format text issue unassign PROJ-123
+jira-cli --format text issue watch PROJ-123
+jira-cli --format text issue unwatch PROJ-123
 jira-cli issue watchers PROJ-123
-jira-cli issue vote PROJ-123
-jira-cli issue unvote PROJ-123
+jira-cli --format text issue vote PROJ-123
+jira-cli --format text issue unvote PROJ-123
 
 # Comments
-jira-cli issue comment add PROJ-123 --body "Fixed in PR #42"
+jira-cli --format text issue comment add PROJ-123 --body "Fixed in PR #42"
 jira-cli issue comment list PROJ-123
-jira-cli issue comment delete PROJ-123 --id <commentId>
+jira-cli --format text issue comment delete PROJ-123 --id <commentId>
 
 # Worklogs
-jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging session"
-jira-cli issue worklog add PROJ-123 --time 1h30m --started "2024-01-15T10:00:00.000+0000"
+jira-cli --format text issue worklog add PROJ-123 --time 2h --comment "Debugging session"
+jira-cli --format text issue worklog add PROJ-123 --time 1h30m --started "2024-01-15T10:00:00.000+0000"
 jira-cli issue worklog list PROJ-123
 
 # Links
 jira-cli issue link-types                                           # List available link types
-jira-cli issue link PROJ-123 --to PROJ-456 --type "blocks"
-jira-cli issue unlink <linkId>
-jira-cli issue remote-link PROJ-123 --url https://pr.url --title "PR #42"
+jira-cli --format text issue link PROJ-123 --to PROJ-456 --type "blocks"
+jira-cli --format text issue unlink <linkId>
+jira-cli --format text issue remote-link PROJ-123 --url https://pr.url --title "PR #42"
 jira-cli issue remote-links PROJ-123
 
 # Attachments
-jira-cli issue attach PROJ-123 --file ./screenshot.png
+jira-cli --format text issue attach PROJ-123 --file ./screenshot.png
 jira-cli issue attachments PROJ-123                              # list metadata (incl. content URL)
 jira-cli issue attachments PROJ-123 --out ./dl                   # download all -> [{id,filename,path,mimeType}]
 jira-cli issue attachments PROJ-123 --out ./dl --id 4609477      # download a single attachment by ID
@@ -153,10 +162,10 @@ jira-cli sprint list --board 42
 jira-cli sprint list --board 42 --state active
 jira-cli sprint active --board 42                                  # Active sprint + issues
 jira-cli sprint issues --sprint 10
-jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14
-jira-cli sprint update --sprint 10 --goal "Complete payment refactor"
-jira-cli sprint move --sprint 10 --issues PROJ-123,PROJ-124,PROJ-125
-jira-cli sprint close --sprint 10
+jira-cli --format text sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14
+jira-cli --format text sprint update --sprint 10 --goal "Complete payment refactor"
+jira-cli --format text sprint move --sprint 10 --issues PROJ-123,PROJ-124,PROJ-125
+jira-cli --format text sprint close --sprint 10
 jira-cli sprint close --sprint 10 --dry-run   # Preview without closing (no confirmation prompt)
 ```
 
@@ -206,11 +215,11 @@ jira-cli user search --query "john" --assignable --project PROJ
 ```bash
 jira-cli filter list
 jira-cli filter get <filterId>
-jira-cli filter create --name "My Bugs" --jql "assignee = me AND type = Bug"
+jira-cli --format text filter create --name "My Bugs" --jql "assignee = me AND type = Bug"
 jira-cli filter run <filterId>
 jira-cli filter run <filterId> --fields key,summary,status   # Output trimming
 jira-cli --format raw filter run <filterId>                  # Raw Jira search response
-jira-cli filter delete <filterId>
+jira-cli --format text filter delete <filterId>
 ```
 
 ## Workflow Examples
@@ -227,10 +236,10 @@ jira-cli issue get PROJ-123
 jira-cli issue transitions PROJ-123
 
 # 4. Transition to Done
-jira-cli issue transition PROJ-123 "Done"
+jira-cli --format text issue transition PROJ-123 "Done"
 
 # 5. Add a comment
-jira-cli issue comment add PROJ-123 --body "Completed and deployed to staging"
+jira-cli --format text issue comment add PROJ-123 --body "Completed and deployed to staging"
 ```
 
 ### Sprint planning workflow
@@ -245,16 +254,17 @@ jira-cli sprint active --board 42
 jira-cli board backlog --board 42
 
 # 4. Create next sprint
-jira-cli sprint create --board 42 --name "Sprint 6" --start-date 2024-02-15 --end-date 2024-02-28
+jira-cli --format text sprint create --board 42 --name "Sprint 6" --start-date 2024-02-15 --end-date 2024-02-28
 
 # 5. Move issues to sprint
-jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
+jira-cli --format text sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
 ```
 
 ## Guardrails
 
-- Always run `jira-cli doctor` and verify **`authValid` is `true`** before bulk operations (exit code 3 on failure)
-- `issue delete` requires typing the issue key to confirm. Use `--force` to skip confirmation in automated workflows; `--dry-run` skips confirmation
+- Always run `jira-cli doctor` and verify **`.data.config.auth_status == "valid"`** before bulk operations (exit code 4 on auth/config failure)
+- In JSON mode, write commands require `--dry-run` followed by `--confirm <token>` unless the command explicitly documents otherwise
+- In text mode, `issue delete` requires typing the issue key to confirm. Use `--force` only when the user explicitly asked to skip that prompt; `--dry-run` skips confirmation
 - `sprint close` has no confirmation prompt — use `--dry-run` to preview; confirm with the user before closing
 - Omit output flags when parsing output in scripts or AI workflows; JSON is the default
 - Use `--dry-run` to preview what a write command would do without executing it
@@ -268,9 +278,10 @@ jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
 - `--format json|text|raw` — Control output format. Default: `json`
 - `--compact` — Emit compact JSON (only with `--format json`)
 - `--json` — Compatibility alias for `--format json`; do not recommend it for new workflows
-- `--force` — Skip interactive confirmation prompts (for CI/Agent automation)
+- `--force` — Skip interactive confirmation prompts in text mode
 - `--quiet` — Suppress auxiliary text output; does not suppress JSON/raw main results
 - `--dry-run` — Show what would be done without executing (supported by write/update commands)
+- `--confirm <token>` — Execute a JSON-mode write command using the token returned by `--dry-run`
 
 ## Output Control Flags
 
@@ -292,20 +303,30 @@ Other read-command flags:
 
 | Command | Default JSON shape |
 |---------|---------------------|
-| `issue list` | Bare array: `[{key, summary, ...}, ...]` |
+All default JSON responses are wrapped:
+
+```json
+{"ok":true,"schema_version":"1.0","data":{},"meta":{"duration_ms":0}}
+```
+
+The command-specific payload is in `.data`:
+
+| Command | `.data` shape |
+|---------|---------------|
+| `issue list` | Array: `[{key, summary, ...}, ...]` |
 | `search`, `filter run` (default) | Object with pagination: `{total, startAt, maxResults, issues: [...]}` |
-| `filter run --fields ...` | Bare trimmed array (like `issue list --fields`) |
+| `filter run --fields ...` | Trimmed array (like `issue list --fields`) |
 | `issue get` | Single flat issue object |
 
 **jq examples:**
 
 ```bash
-jira-cli issue list --project PROJ | jq '.[].key'
-jira-cli search "project = PROJ" | jq '.issues[].key'
-jira-cli filter run 12345 | jq '.issues[].status'
+jira-cli issue list --project PROJ | jq '.data[].key'
+jira-cli search "project = PROJ" | jq '.data.issues[].key'
+jira-cli filter run 12345 | jq '.data.issues[].status'
 ```
 
-### Flat Issue (default JSON)
+### Flat Issue (`.data` in default JSON)
 
 ```json
 {
@@ -324,7 +345,7 @@ jira-cli filter run 12345 | jq '.issues[].status'
 }
 ```
 
-### Flat Sprint
+### Flat Sprint (`.data` in default JSON)
 
 ```json
 {
@@ -337,40 +358,52 @@ jira-cli filter run 12345 | jq '.issues[].status'
 }
 ```
 
-### Error Response (default JSON, written to stderr)
+### Error Response (default JSON, written to stdout)
 
 ```json
 {
-  "error": "Jira API error 404: Issue does not exist",
-  "statusCode": 404,
-  "errorCode": "NOT_FOUND",
-  "hint": "Verify the issue key exists and you have permission to view it"
+  "ok": false,
+  "schema_version": "1.0",
+  "error": {
+    "code": "E_NOT_FOUND",
+    "message": "Jira API error 404: Issue does not exist",
+    "details": {
+      "status_code": 404,
+      "hint": "Verify the resource key/ID exists and you have permission to view it"
+    },
+    "retryable": false
+  }
 }
 ```
 
 ### Error Codes
 
-| Code | Status | Hint |
-|------|--------|------|
-| `AUTH_REQUIRED` | 401 | Run `jira-cli login` or set JIRA_HOST and JIRA_TOKEN |
-| `FORBIDDEN` | 403 | Check your PAT scope and project permissions |
-| `NOT_FOUND` | 404 | Verify the resource key/ID exists |
-| `RATE_LIMITED` | 429 | Wait and retry; reduce request frequency |
-| `SERVER_ERROR` | 5xx | Jira server error; retry later |
-| `NETWORK_ERROR` | — | Check host URL and network connectivity |
-| `CONFIG_ERROR` | — | Run `jira-cli login` or set env vars |
+| Code | Status | Retryable | Hint |
+|------|--------|-----------|------|
+| `E_AUTH_REQUIRED` | 401 | false | Run `jira-cli login --host <url> --token <pat>` or set env vars |
+| `E_FORBIDDEN` | 403 | false | Check your PAT scope and project permissions |
+| `E_NOT_FOUND` | 404 | false | Verify the resource key/ID exists |
+| `E_RATE_LIMITED` | 429 | true | Wait and retry with backoff |
+| `E_SERVER` | 5xx | true | Jira server error; retry later |
+| `E_NETWORK` | — | true | Check host URL and network connectivity |
+| `E_CONFIG` | — | false | Run `jira-cli login --host <url> --token <pat>` or set env vars |
+| `E_CONFIRM_REQUIRED` | — | false | Run the same write command with `--dry-run`, then retry with `--confirm <token>` |
+| `E_CONFLICT` | — | false | Re-run `--dry-run`; the token no longer matches the operation |
+| `E_TIMEOUT` | 408 | true | Retry with backoff |
 
 ### Exit Codes
 
 | Code | Meaning |
 |------|---------|
 | 0 | Success |
+| 1 | Generic error |
 | 2 | Bad arguments |
-| 3 | Authentication error |
-| 4 | Resource not found |
-| 5 | Forbidden |
-| 6 | Rate limited |
-| 7 | Network/server error |
+| 3 | Resource not found |
+| 4 | Authentication or permission error |
+| 5 | Confirmation token required |
+| 6 | Conflict / stale confirmation token |
+| 7 | Retryable transient error |
+| 8 | Timeout |
 
 ## Audit Logging
 
@@ -384,5 +417,7 @@ All write commands are automatically logged to `~/.jira-cli/audit/` in JSONL for
 ## Self-Description
 
 ```bash
-jira-cli reference   # Print all commands, subcommands, and flags in structured markdown
+jira-cli reference   # Structured JSON command reference
+jira-cli context     # Runtime, config, and credential status
+jira-cli doctor      # Environment and connectivity checks
 ```