Merge pull request #191 from hdresearch/feat/agent-native-cli-fixes-2

feat: agent-native CLI fixes round 2 (F11, F14, F18)

Author: AlephNotation

F1-json-flag.md

@@ -132,6 +132,29 @@ vers tag delete <name>
 vers tag delete <name-1> <name-2>
 ```
 
+### Feedback
+
+Report friction (or anything else) about the CLI. Entries are appended to a
+local JSONL journal at `~/.vers/feedback.jsonl`.
+
+```bash
+# Record locally
+vers feedback "the --tier flag rejects 'enterprise' but docs list it as valid"
+
+# List recent entries
+vers feedback list
+vers feedback list --limit 5 --json
+
+# Opt-in upstream delivery: when VERS_FEEDBACK_ENDPOINT is set, the entry is
+# also POSTed there (application/json, 5s timeout). Failures are logged to
+# stderr but the local journal entry is still written.
+VERS_FEEDBACK_ENDPOINT=https://example.com/cli-feedback \
+  vers feedback "race condition in --wait when job completes during first poll"
+```
+
+Override the journal path with `VERS_FEEDBACK_PATH` (primarily for testing).
+
+
 ### Shell Composition
 
 Commands with `-q` output are designed to compose with standard Unix tools:
@@ -159,6 +182,24 @@ vers get <vm-id> --json | jq '.ip'
 vers ps -q
 ```
 
+### Job Ledger
+
+Every `--wait` invocation of `run`, `branch`, `deploy`, `resume`, or `run-commit`
+appends an entry to a durable JSONL ledger at `~/.vers/jobs.jsonl` (override
+with `VERS_JOBS_DIR`). Use `vers jobs` to introspect:
+
+```bash
+vers jobs list --json                     # all jobs as JSON
+vers jobs list --status failed            # only failed jobs
+vers jobs get job_<id>                    # full record for one job
+vers jobs prune --older-than 7d           # trim entries older than 7 days
+vers jobs prune --all --dry-run           # preview clearing the ledger
+```
+
+Phase 1 ships journaling only. The ledger is written best-effort: a write
+failure never causes the underlying command to fail. Resumption of in-flight
+jobs is not yet implemented.
+
 
 ## Configuration