diff --git a/changelog.mdx b/changelog.mdx
index f297d98..e455af7 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -7,6 +7,21 @@ description: "Stay up to date with the latest agentsfleet product updates, new f
agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner.
+
+ ## Every command answers a mistyped invocation the same way
+
+ A missing argument used to be reported one of two ways depending on which command you ran. `agentsfleet logs` named what was missing and exited `4`; `agentsfleet events` printed a bare parser message, offered no way to fix it, and exited `2` — the same code a network failure returns, so a script could not tell a typo from an unreachable daemon. Every command now prints what is missing and the command that supplies it, and every rejected invocation exits `4`. Exit `2` means a network failure and nothing else.
+
+ ## What's new
+
+ - **A rejection names the fix, not just the fault.** `agentsfleet events` answers `✕ error: missing required argument 'fleet_id'` followed by `Suggestion: usage: agentsfleet events [options] `.
+ - **An unknown command still suggests the nearest match** and points at the command list it belongs to.
+ - **`--json` rejections are parseable.** A rejected invocation emits `{"error":{"code","message"}}` on standard error with a stable `code` — `MISSING_ARGUMENT`, `MISSING_OPTION_VALUE`, `MISSING_REQUIRED_OPTION`, `UNKNOWN_COMMAND`, `UNKNOWN_OPTION`, `INVALID_ARGUMENT`, or `EXCESS_ARGUMENTS`. It printed human text before.
+ - **A command group run bare prints help on standard output,** so `agentsfleet workspace | less` is no longer empty. It went to standard error while exiting `0`.
+ - **`agentsfleet logs` stops repeating itself.** Its suggestion line said the same sentence as the error above it; it now carries the runnable usage line, as `grant list` now does too.
+ - **The published exit-code table is what the client does.** [The command reference](/cli/agentsfleet#errors) listed `2` as covering invalid input as well as network failure; that row is now network failure alone.
+
+
## A hardened runner completes credentialed work again
diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx
index e915242..37da05e 100644
--- a/cli/agentsfleet.mdx
+++ b/cli/agentsfleet.mdx
@@ -151,12 +151,33 @@ credential.
|---|---|
| `0` | The command succeeded. |
| `1` | Authentication, session, or unexpected failure. |
-| `2` | Network failure, rate limit, or invalid command input. |
+| `2` | Network failure or rate limit. |
| `3` | The API returned a server failure. |
-| `4` | A supplied value failed validation. |
+| `4` | The invocation was rejected: a missing argument, a missing or unrecognized flag, a value that failed validation, or an unknown command. |
| `5` | Local configuration is missing or invalid. |
| `130` | You interrupted the command. |
+A rejected invocation is answered before any request is sent. The form is always the same: what is wrong, then the command that puts it right. What is wrong may be an absent argument, a value that failed validation, or an unrecognized command.
+
+```
+$ agentsfleet events
+✕ error: missing required argument 'fleet_id'
+ Suggestion: usage: agentsfleet events [options]
+```
+
+Under `--json` the same rejection is a parseable envelope on standard error, carrying a stable `code` you can switch on:
+
+```json
+{
+ "error": {
+ "code": "MISSING_ARGUMENT",
+ "message": "missing required argument 'fleet_id'"
+ }
+}
+```
+
+The codes are `MISSING_ARGUMENT`, `MISSING_OPTION_VALUE`, `MISSING_REQUIRED_OPTION`, `UNKNOWN_COMMAND`, `UNKNOWN_OPTION`, `INVALID_ARGUMENT`, and `EXCESS_ARGUMENTS`.
+
API failures include a stable error code and request identifier when the server supplies them. Use both values when reporting a problem.
## Related pages
diff --git a/cli/flags.mdx b/cli/flags.mdx
index 3edfed3..c13a579 100644
--- a/cli/flags.mdx
+++ b/cli/flags.mdx
@@ -51,6 +51,8 @@ Invalid command input returns `4`. Local configuration failures return `5`.
An interrupted browser login returns `130`.
+A command group run without a subcommand prints its help on standard output and exits `0`, so `agentsfleet workspace | less` shows the same body `agentsfleet workspace --help` does.
+
JSON errors include the stable product error identifier when the API supplies one. See the [error registry](/api-reference/error-codes).
## Related pages