When documenting behavior, never leave exception cases implicit.
Standard
- Use a dedicated “Caveats” (callout) section/table for any rule that has exceptions, ignored inputs, timeouts, or different behavior by environment (CLI vs extension vs provider, OS, etc.).
- Explain the “why,” not just the symptom: describe the class of conditions that causes the exception (e.g., provider/tooling that runs parts internally), not only a potentially non-exhaustive list.
- Match the real contract: options and fields must reflect actual behavior. If something is misleading (e.g., “accepted but ignored”), remove the row or explicitly omit it rather than encouraging incorrect usage.
- Keep tables/examples consistent with
--help/actual semantics (e.g., ordering, defaults, return formats).
Example (docs pattern)
## Caveats
- **Hooks won’t run** when the model-provider executes tool processing internally.
- Only events `PreToolUse` / `PostToolUse` accept replies in the CLI+Desktop; other events start asynchronously and their replies are ignored.
Example (option table correction)
- If
--limit semantics differ (e.g., newest-first), update the table text rather than leaving it ambiguous.
- If an option is “accepted but ignored,” remove or revise the documentation entry to prevent users from relying on it.