From 70b2f6a66fd9855ed8f656bde47a24db73df0fea Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Wed, 22 Apr 2026 21:19:03 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20USAGE.md=20=E2=80=94=20cross-link=20ERR?= =?UTF-8?q?OR=5FHANDLING.md=20for=20subprocess=20orchestration?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cycle #25 ships navigation improvements connecting USAGE (setup/interactive) to ERROR_HANDLING.md (subprocess/orchestration patterns). Before: USAGE.md had JSON scripting mention but no link to error-handling guide. New users reading USAGE would see JSON is available, but wouldn't discover the error-handling pattern without accidentally finding ERROR_HANDLING.md. After: Two strategic cross-links: 1. Top-level tip box: "Building orchestration code? See ERROR_HANDLING.md" 2. JSON scripting section expanded with examples + link to unified pattern Changes to USAGE.md: - Added TIP callout near top linking to ERROR_HANDLING.md - Expanded "JSON output for scripting" section: - Explains what the envelope contains (exit_code, command, timestamp, fields) - Added 3 command examples (prompt, load-session, turn-loop) - Added callout for dispatchers/orchestrators pointing to ERROR_HANDLING pattern Impact: Operators reading USAGE for "how do I call claw from scripts?" now immediately see the canonical answer (ERROR_HANDLING.md) instead of having to reverse-engineer it from code examples. No code changes. Pure navigation/documentation. Continues the documentation-governance pattern: the work protocol (14 clawable commands) has a consumption guide (ERROR_HANDLING.md), and that guide is now reachable from the main entry point (USAGE.md + README.md top nav). --- USAGE.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/USAGE.md b/USAGE.md index c8e7b09..440603c 100644 --- a/USAGE.md +++ b/USAGE.md @@ -2,6 +2,9 @@ This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary. If you are brand new, make the doctor health check your first run: start `claw`, then run `/doctor`. +> [!TIP] +> **Building orchestration code that calls `claw` as a subprocess?** See [`ERROR_HANDLING.md`](./ERROR_HANDLING.md) for the unified error-handling pattern (one handler for all 14 clawable commands, exit codes, JSON envelope contract, and recovery strategies). + ## Quick-start health check Run this before prompts, sessions, or automation: @@ -95,11 +98,17 @@ cd rust ### JSON output for scripting +All clawable commands support `--output-format json` for machine-readable output. Every invocation returns a consistent JSON envelope with `exit_code`, `command`, `timestamp`, and either `{success fields}` or `{error: {kind, message, ...}}`. + ```bash cd rust ./target/debug/claw --output-format json prompt "status" +./target/debug/claw --output-format json load-session my-session-id +./target/debug/claw --output-format json turn-loop "analyze logs" --max-turns 1 ``` +**Building a dispatcher or orchestration script?** See [`ERROR_HANDLING.md`](./ERROR_HANDLING.md) for the unified error-handling pattern. One code example works for all 14 clawable commands: parse the exit code, classify by `error.kind`, apply recovery strategies (retry, timeout recovery, validation, logging). Use that pattern instead of reimplementing error handling per command. + ### Inspect worker state The `claw state` command reads `.claw/worker-state.json`, which is written by the interactive REPL or a one-shot prompt when a worker executes a task. This file contains the worker ID, session reference, model, and permission mode.