Merge pull request #879 from fabro-sh/codex/approval-interview-guidance

Document when to use approve/deny versus human interview gates

docs/public/reference/cli.mdx

@@ -63,7 +63,7 @@ fabro [OPTIONS] [COMMAND]
 
 | Command | Description |
 | --- | --- |
-| `fabro approve` | Approve pending workflow runs |
+| `fabro approve` | Approve a pending run for execution |
 | `fabro archive` | Mark terminal runs as archived (reviewed, no further action needed). Archived runs are hidden from default listings |
 | `fabro artifact` | Inspect and copy run artifacts (screenshots, reports, traces) |
 | `fabro ask` | Ask Fabro a read-only question about a run |
@@ -71,7 +71,7 @@ fabro [OPTIONS] [COMMAND]
 | `fabro auth` | Manage CLI authentication state |
 | `fabro completion` | Generate shell completions |
 | `fabro create` | Register a workflow version and create a submitted run |
-| `fabro deny` | Deny pending workflow runs |
+| `fabro deny` | Deny execution of a pending run |
 | `fabro discord` | Open the Discord community in the browser |
 | `fabro docs` | Open the docs website in the browser |
 | `fabro doctor` | Check environment and integration health |
@@ -111,7 +111,7 @@ fabro [OPTIONS] [COMMAND]
 
 ### `fabro approve`
 
-Approve pending workflow runs
+Approve a pending run for execution
 
 ```bash
 fabro approve [OPTIONS] <RUNS>...
@@ -371,7 +371,7 @@ fabro create [OPTIONS] <WORKFLOW>
 
 ### `fabro deny`
 
-Deny pending workflow runs
+Deny execution of a pending run
 
 ```bash
 fabro deny [OPTIONS] <RUNS>...

docs/public/workflows/human-in-the-loop.mdx

@@ -19,6 +19,14 @@ approve -> skip      [label="[S] Skip"]
 
 When execution reaches the gate, the user sees the previous stage's output followed by the node's label ("Approve Plan") and the available options. In the CLI, this appears as an interactive menu. In the web UI, blocked runs show an interview dock on the run page where the user can answer the pending question.
 
+<Note>
+`fabro approve` and `fabro deny` grant or deny permission to **start a run** waiting
+for execution approval. To answer a human gate during execution, run
+`fabro attach <run>` for an interactive prompt or use the run page's interview dock.
+API clients can list pending questions with `GET /api/v1/runs/{id}/questions` and
+answer a specific question with `POST /api/v1/runs/{id}/questions/{qid}/answer`.
+</Note>
+
 ### Keyboard accelerators
 
 The prefixes `[A]`, `[R]`, `[S]` in edge labels serve as keyboard accelerators. Fabro supports three formats:

lib/apps/fabro-cli/src/args.rs

@@ -1357,9 +1357,9 @@ pub(crate) enum RunsCommands {
     Rm(RunsRemoveArgs),
     /// Show detailed information about a workflow run
     Inspect(InspectArgs),
-    /// Approve pending workflow runs.
+    /// Approve a pending run for execution.
     Approve(RunsApproveArgs),
-    /// Deny pending workflow runs.
+    /// Deny execution of a pending run.
     Deny(RunsDenyArgs),
     /// Mark terminal runs as archived (reviewed, no further action needed).
     /// Archived runs are hidden from default listings.

lib/apps/fabro-cli/tests/it/cmd/approve.rs

@@ -14,7 +14,7 @@ fn help() {
     success: true
     exit_code: 0
     ----- stdout -----
-    Approve pending workflow runs
+    Approve a pending run for execution
 
     Usage: fabro approve [OPTIONS] <RUNS>...
 

lib/apps/fabro-cli/tests/it/cmd/deny.rs

@@ -14,7 +14,7 @@ fn help() {
     success: true
     exit_code: 0
     ----- stdout -----
-    Deny pending workflow runs
+    Deny execution of a pending run
 
     Usage: fabro deny [OPTIONS] <RUNS>...
 

lib/apps/fabro-cli/tests/it/cmd/fabro.rs

@@ -31,8 +31,8 @@ fn help() {
       dump        Export a run's durable state to a directory
       rm          Remove one or more workflow runs
       inspect     Show detailed information about a workflow run
-      approve     Approve pending workflow runs
-      deny        Deny pending workflow runs
+      approve     Approve a pending run for execution
+      deny        Deny execution of a pending run
       archive     Mark terminal runs as archived (reviewed, no further action needed). Archived runs are hidden from default listings
       unarchive   Restore archived runs to their prior terminal status
       model       List and test LLM models