Distinguish the three prerequisite-check failure modes

`foundry version`, `foundry profile active`, and `foundry apps list` fail for unrelated reasons, and the skill treated them as one class, so an agent that hit any of them went looking for broken credentials.

Only `apps list` reaches the tenant; the other two read local state. So a failure there while `profile active` succeeds rules out credentials and points at network, an approval gate, or an old CLI. `apps list` also landed in CLI 2.0.2, and on anything older it fails as an unknown command, which reads like an auth error but is not one. It exists to catch app-name collisions, so skipping it costs a collision check rather than the workflow.

Adds the approval-gate case, which assistants that run only a small trusted command set unattended will hit on every `foundry` call. A denied or still-pending command has produced no evidence either way, so it should not be retried in a loop or answered by rewriting profiles and config paths. Ask once, or hand the user the command.

Detail lives in the headless-operation reference because SKILL.md is at 99% of its size budget.

Author: mraible

skills/development-workflow/SKILL.md

@@ -142,13 +142,15 @@ For other decisions, prefer reasonable defaults: use React for UI, download publ
 
 ```bash
 foundry version          # Verify CLI installed
-foundry profile active   # Verify authentication
-foundry apps list        # Check existing apps (avoid name collisions)
+foundry profile active   # Verify credentials (reads local config only)
+foundry apps list        # First call that reaches the tenant; CLI 2.0.2+
 ```
 
-If any of these fail, see [headless operation](references/headless-operation.md)
-for setup options (env vars, non-interactive profile creation) and sandbox
-diagnostics. Never copy credentials into the workspace.
+`foundry apps list` is optional, for avoiding name collisions. An "unknown
+command" error means a CLI older than 2.0.2, not broken auth. Because it is the
+first command to reach the tenant, failing it while `profile active` succeeds
+points at network or a pending approval prompt rather than credentials. See
+[headless operation](references/headless-operation.md).
 
 ### Step 4: Scaffold the App
 

skills/development-workflow/references/headless-operation.md

@@ -116,6 +116,24 @@ When operating as a CLI agent:
 6. **Headless mode** is detected automatically by Foundry CLI v2.0.1+. For older versions or standalone scripts/CI, export `FOUNDRY_UI_HEADLESS_MODE=true` manually.
 7. **Choose the app directory automatically:** Use the current directory unless it is an unrelated repository; in that case use a sibling directory and request write access if the sandbox requires it.
 
+### Distinguishing prerequisite failures
+
+The three prerequisite commands fail for different reasons, and treating them alike sends the diagnosis down the wrong path:
+
+| Command | Reaches tenant? | A failure means |
+|---------|-----------------|-----------------|
+| `foundry version` | No | CLI not installed or not on `PATH` |
+| `foundry profile active` | No, reads local config | No profile configured — set env vars or create one non-interactively |
+| `foundry apps list` | Yes | Network, an approval gate, or a CLI older than 2.0.2 — not credentials, if `profile active` succeeded |
+
+`foundry apps list` arrived in Foundry CLI 2.0.2. On an older CLI it fails as an unknown or unrecognized command, which is not an authentication problem. Report the CLI version and move on; the command is only there to avoid app-name collisions, so losing it costs a collision check, not the workflow.
+
+### Commands gated behind user approval
+
+Some assistants run only a small trusted set of commands (`ls`, `cat`, `sed`) unattended and escalate everything else for user approval. `foundry` is never in that set, so every invocation can surface an approval request.
+
+A command that was denied, or that never ran because approval was still pending, has produced no evidence about credentials or connectivity. Do not treat it as an auth failure, do not retry it in a loop hoping it slips through, and do not start rewriting profiles or config paths. Ask the user once to approve it, or give them the command to run and paste back. If the assistant supports a persistent allowlist, suggest adding read-only Foundry commands to it so the prerequisite check stops prompting.
+
 ### Sandboxed assistants
 
 Some assistants run shell commands with network sandboxing. A profile command can succeed because it only reads local configuration, while a tenant command such as `foundry apps list` or `foundry apps validate` fails with only `connection issue`. The CLI holds client credentials on disk and exchanges them for a short-lived token in memory on each run, so it never needs to write to the config directory — a tenant failure points at network access, not file permissions.