docs: align init agent JSON docs with settlement envelopes (#1776)

init --agent/--json on v1 emits settlement envelopes (ok, dotted CLI.*
codes, nextActions), matching check --json. reference/init.mdx and
skills/arkenv/SKILL.md still taught status/retryWith.

This PR updates both to the ErroredEnvelope shape (CLI.GIT_TREE_DIRTY +
nextActions run-command) and the ok:true success path. Leaves dev/main
machine-readable-output.mdx alone (v1 focus). Docs/skill only, no
changeset.

Author: yamcodes

apps/www/content/docs/guides/ai.mdx

@@ -82,7 +82,7 @@ public prefixes, and skip a `runtimeEnv` map.
 **Greenfield setup**
 
 ```text
-Add ArkEnv to this repo. Run `npx arkenv init --agent`, parse the JSON on stdout, and only retry with flags from `retryWith` if a refusal is safe to bypass. Do not hand-write next.config or env.ts unless init fails.
+Add ArkEnv to this repo. Run `npx arkenv init --agent`, parse the JSON on stdout, and only retry with `--force` if the refusal's `nextActions` include a `run-command` with `--force`. Do not hand-write next.config or env.ts unless init fails.
 ```
 
 **Existing keys**

apps/www/content/docs/reference/agent-plugin.mdx

@@ -41,7 +41,7 @@ a follow-up to `plugins add`.
 ## Commands
 
 Two slash commands wrap the CLI and the auditor. Parse JSON on stdout.
-Do not pass `--force` unless a refusal lists it in `retryWith`.
+Do not pass `--force` unless a refusal's `nextActions` include a `--force` run-command.
 
 ### `/arkenv:init`
 

apps/www/content/docs/reference/init.mdx

@@ -52,20 +52,42 @@ See [Hosting presets](/docs/core-concepts/hosting-presets).
 Same macro as the [global `--agent` flag](/docs/reference#agent):
 `--yes --quiet --json`. It does not imply `--force`.
 
-When a safety check fails (dirty git tree), stdout is a JSON refusal and
-the process exits non-zero:
+When a safety check fails (dirty git tree), stdout is an errored
+settlement envelope (`ok: false`) and the process exits non-zero:
 
 ```json
 {
-  "status": "error",
-  "code": "GIT_TREE_DIRTY",
-  "message": "Git working tree is not clean.",
-  "retryWith": ["--force"]
+  "ok": false,
+  "commandId": "init",
+  "error": {
+    "code": "CLI.GIT_TREE_DIRTY",
+    "severity": "error",
+    "summary": "Git working tree is not clean.",
+    "why": "Commit or stash your changes before running arkenv init.",
+    "nextActions": [
+      {
+        "kind": "run-command",
+        "label": "Re-run with --force to bypass git working tree check",
+        "command": "arkenv init --force"
+      }
+    ]
+  },
+  "diagnostics": [],
+  "nextActions": [
+    {
+      "kind": "run-command",
+      "label": "Re-run with --force to bypass git working tree check",
+      "command": "arkenv init --force"
+    }
+  ]
 }
 ```
 
-Only rerun with flags in `retryWith` after you confirm the bypass is
-safe.
+Branch on `error.code` (dotted `CLI.*` / `ENV.*` codes). Use
+`nextActions` for remediation — a `run-command` action with `--force`
+means the refusal is bypassable. Only re-run with that flag after you
+confirm the bypass is safe. The same envelope shape is documented for
+[`check --json`](/docs/reference/check#json--j).
 
 ### `--example <name>`
 

skills/arkenv/SKILL.md

@@ -49,25 +49,44 @@ AI agents SHOULD always use the CLI for project initialization to ensure consist
   - **`--yes`**: Bypasses all interactive prompts and uses recommended defaults.
   - **`--quiet`**: Suppresses spinners and ANSI formatting for cleaner terminal logs.
   - **`--json`**: Emits a structured JSON summary to `stdout` upon completion (all other output is sent to `stderr`).
-- **Success Verification**: Parse the JSON output to verify `status: "success"` and retrieve details like the scaffolded file path.
+- **Success Verification**: Parse the JSON settlement envelope on `stdout`. Success is `ok: true` with `commandId: "init"`; details (e.g. scaffolded paths) live under `result`.
 
-#### Handling refusals (`status: "error"`)
+#### Handling refusals (`ok: false`)
 
-`--agent` **never** implies `--force`. When a safety check trips, the CLI refuses and emits a machine-actionable JSON payload to `stdout`:
+`--agent` **never** implies `--force`. When a safety check trips, the CLI refuses and emits an errored settlement envelope to `stdout`:
 
 ```json
 {
-  "status": "error",
-  "code": "GIT_TREE_DIRTY",
-  "message": "Git working tree is not clean.",
-  "retryWith": ["--force"]
+  "ok": false,
+  "commandId": "init",
+  "error": {
+    "code": "CLI.GIT_TREE_DIRTY",
+    "severity": "error",
+    "summary": "Git working tree is not clean.",
+    "why": "Commit or stash your changes before running arkenv init.",
+    "nextActions": [
+      {
+        "kind": "run-command",
+        "label": "Re-run with --force to bypass git working tree check",
+        "command": "arkenv init --force"
+      }
+    ]
+  },
+  "diagnostics": [],
+  "nextActions": [
+    {
+      "kind": "run-command",
+      "label": "Re-run with --force to bypass git working tree check",
+      "command": "arkenv init --force"
+    }
+  ]
 }
 ```
 
-- **`code`**: a stable identifier you can branch on. Refusal codes: `REQUIREMENTS_NOT_MET`, `GIT_TREE_DIRTY`, `NON_EMPTY_DIR`. A `code` of `INTERNAL` means the CLI *broke* rather than *refused* - retrying with flags will not help.
-- **`retryWith`**: the flag(s) that would bypass the check (e.g. `["--force"]`). Empty (`[]`) means the refusal is not bypassable.
+- **`error.code`**: a stable dotted identifier you can branch on (`CLI.REQUIREMENTS_NOT_MET`, `CLI.GIT_TREE_DIRTY`, `CLI.NON_EMPTY_DIR`, …). `CLI.INTERNAL_ERROR` means the CLI *broke* rather than *refused* — retrying with flags will not help.
+- **`nextActions`**: remediation steps. A `run-command` action that includes `--force` means the refusal is bypassable; empty `nextActions` means it is not. Prefer `nextActions` over any legacy `retryWith` field.
 
-**Escalation pattern**: always run `init --agent` **without** `--force` first. If you get `status: "error"`, inspect `code` and `retryWith`. Only re-run with the flag(s) from `retryWith` (e.g. append `--force`) once you have deliberately decided the refusal is safe to bypass - do not add `--force` pre-emptively.
+**Escalation pattern**: always run `init --agent` **without** `--force` first. If you get `ok: false`, inspect `error.code` and `nextActions`. Only re-run with `--force` (or the command from a `run-command` action) once you have deliberately decided the refusal is safe to bypass — do not add `--force` pre-emptively.
 
 ---