feat(cli): default amy stdout to human-readable text; --json opts in

amy's default stdout is now a YAML-ish render of the underlying result
map; the previous single-line JSON contract moves behind a global
`--json` flag. Errors mirror the same rule (`error: <code>: <detail>`
on stderr by default, JSON `{"error":...,"detail":...}` under --json).
Exit codes (0/1/2/124) and the --json shape itself are unchanged —
only the default presentation flips.

- Replaces Json.writeLine / Json.error with mode-aware
  Output.emit / Output.error. The same Jackson mapper is reused for
  on-disk JSON via Output.mapper.
- Adds `--json` to the global flag set in Main.kt; honoured even when
  argument parsing fails so error JSON keeps shape under --json.
- Updates the test harness wrappers (amy_a / amy_b / amy_d in
  cli/tests/{headless,dm,cache}/) and the few direct $AMY_BIN call
  sites whose stdout is consumed via $() / 2>&1 — they now pass
  --json so the existing jq pipelines keep working.
- Rewrites the README "Output contract" and DEVELOPMENT design
  principles to describe the new default, and clarifies that only
  --json is the public API; the text shape is allowed to drift.

cli/tests/dm/setup.sh

@@ -75,15 +75,15 @@ preflight_dm() {
 # `--secret-backend=plaintext` keeps these throwaway interop runs headless —
 # the default `auto` would try the OS keychain (not available in CI) and then
 # ask for a NIP-49 passphrase. Plaintext still writes 0600-owner-only.
-amy_a() { "$AMY_BIN" --data-dir "$A_DIR" --secret-backend plaintext "$@"; }
-amy_d() { "$AMY_BIN" --data-dir "$D_DIR" --secret-backend plaintext "$@"; }
+amy_a() { "$AMY_BIN" --data-dir "$A_DIR" --secret-backend plaintext --json "$@"; }
+amy_d() { "$AMY_BIN" --data-dir "$D_DIR" --secret-backend plaintext --json "$@"; }
 
 # --- identity bootstrap ------------------------------------------------------
 ensure_identity_for() {
   local who="$1" dir="$2"
   step "initialising Identity $who (amy at $dir)"
   local out
-  out=$("$AMY_BIN" --data-dir "$dir" --secret-backend plaintext init) || {
+  out=$("$AMY_BIN" --data-dir "$dir" --secret-backend plaintext --json init) || {
     fail_msg "amy init failed for $who: $out"; exit 1
   }
   local npub hex

cli/tests/dm/tests-dm.sh

@@ -13,10 +13,12 @@
 #   dm-06   cursor advance (subsequent no-flag `dm list` is empty)
 
 # Wrap amy_json around either data-dir so the per-test code stays tight.
+# `--json` opts into amy's machine-readable contract; assertions below
+# parse with jq.
 amy_json_for() {
   local dir="$1"; shift
   local out
-  if ! out=$("$AMY_BIN" --data-dir "$dir" "$@" 2>>"$LOG_FILE"); then
+  if ! out=$("$AMY_BIN" --data-dir "$dir" --json "$@" 2>>"$LOG_FILE"); then
     fail_msg "amy --data-dir $dir $*: exit $? (see $LOG_FILE)"
     printf '%s\n' "$out" >>"$LOG_FILE"
     return 1
@@ -91,7 +93,7 @@ test_03_dm_send_rejects_no_inbox() {
   # Generate a throwaway identity but do NOT publish its kind:10050.
   local tmpdir; tmpdir=$(mktemp -d "${STATE_DIR}/ghost.XXXXXX")
   local ghost_out ghost_npub
-  ghost_out=$("$AMY_BIN" --data-dir "$tmpdir" --secret-backend plaintext init) || {
+  ghost_out=$("$AMY_BIN" --data-dir "$tmpdir" --secret-backend plaintext --json init) || {
     record_result "$id" fail "ghost init failed"; rm -rf "$tmpdir"; return
   }
   ghost_npub=$(printf '%s' "$ghost_out" | jq -r '.npub')
@@ -99,7 +101,7 @@ test_03_dm_send_rejects_no_inbox() {
 
   # A sends without --allow-fallback; amy should refuse.
   local raw rc
-  raw=$("$AMY_BIN" --data-dir "$A_DIR" dm send "$ghost_npub" "should be rejected" 2>&1)
+  raw=$("$AMY_BIN" --data-dir "$A_DIR" --json dm send "$ghost_npub" "should be rejected" 2>&1)
   rc=$?
   rm -rf "$tmpdir"
   if [[ "$rc" -ne 0 ]] && printf '%s' "$raw" | grep -q '"error":"no_dm_relays"'; then
@@ -121,7 +123,7 @@ test_04_dm_send_allow_fallback() {
   # publish should succeed even though the ghost has no 10050.
   local tmpdir; tmpdir=$(mktemp -d "${STATE_DIR}/ghost.XXXXXX")
   local ghost_out ghost_npub
-  ghost_out=$("$AMY_BIN" --data-dir "$tmpdir" --secret-backend plaintext init) || {
+  ghost_out=$("$AMY_BIN" --data-dir "$tmpdir" --secret-backend plaintext --json init) || {
     record_result "$id" fail "ghost init failed"; rm -rf "$tmpdir"; return
   }
   ghost_npub=$(printf '%s' "$ghost_out" | jq -r '.npub')