cli: make bundled help self-describing

2026-03-22 23:37:38 +08:00
parent 5859ff219e
commit 4d8c90eb26
49 changed files with 792 additions and 29 deletions
@@ -33,6 +33,22 @@ func newCompleteCmd(root *rootOptions, mode string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   mode,
 		Short: map[string]string{"done": "Mark a thread complete", "fail": "Mark a thread failed"}[mode],
+		Long: map[string]string{
+			"done": helpLong(
+				"Use done to close a claimed thread successfully and record the final result summary.",
+				"done is a terminal operation; use it only when the work is complete enough to hand back to the leader.",
+				"Include a short summary and optionally a detailed body or artifacts for the final result.",
+			),
+			"fail": helpLong(
+				"Use fail to close a claimed thread unsuccessfully and record the failure summary.",
+				"fail is a terminal operation; use it when the attempt cannot complete successfully.",
+				"Include a short summary and enough detail for the leader to decide on retry, reassignment, or cancellation.",
+			),
+		}[mode],
+		Example: map[string]string{
+			"done": `  inbox --db .agents/coord.db done --agent worker-a --thread thr_123 --summary "Implemented retry policy" --body "Retries now cover read timeouts."`,
+			"fail": `  inbox --db .agents/coord.db fail --agent worker-a --thread thr_123 --summary "Blocked by migration issue" --body "Previous schema state is inconsistent."`,
+		}[mode],
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()