diff --git a/docs/src/content/docs/guides/packaging-imports.md b/docs/src/content/docs/guides/packaging-imports.md
index 76ba2ffad1b..cc9062ac434 100644
--- a/docs/src/content/docs/guides/packaging-imports.md
+++ b/docs/src/content/docs/guides/packaging-imports.md
@@ -23,10 +23,15 @@ gh aw add-wizard https://github.com/githubnext/agentics/blob/main/workflows/dail
 
 # Short form (for workflows in top-level workflows/ directory)
 gh aw add-wizard githubnext/agentics/daily-repo-status
+
+# Skip the API key prompt when a secret is already configured
+gh aw add-wizard githubnext/agentics/daily-repo-status --skip-secret
 ```
 
 This checks requirements, adds the workflow markdown file to your repository, and generates the corresponding YAML workflow. After adding, commit and push the changes to your repository.
 
+The `--skip-secret` flag bypasses the interactive API key prompt. Use it when the required secret (e.g., `COPILOT_GITHUB_TOKEN`) is already configured at the organisation or repository level.
+
 For non-interactive installation, use `gh aw add` with optional versioning. By default this looks in the `workflows/` directory, but you can specify an explicit path if needed:
 
 ```bash wrap
diff --git a/docs/src/content/docs/reference/safe-outputs-pull-requests.md b/docs/src/content/docs/reference/safe-outputs-pull-requests.md
index b50f6936685..1c3b4961b74 100644
--- a/docs/src/content/docs/reference/safe-outputs-pull-requests.md
+++ b/docs/src/content/docs/reference/safe-outputs-pull-requests.md
@@ -21,7 +21,7 @@ safe-outputs:
     title-prefix: "[ai] "         # prefix for titles
     labels: [automation]          # labels to attach
     reviewers: [user1, copilot]   # reviewers (use 'copilot' for bot)
-    draft: true                   # create as draft (default: true)
+    draft: true                   # create as draft — enforced as policy (default: true)
     max: 3                        # max PRs per run (default: 1)
     expires: 14                   # auto-close after 14 days (same-repo only)
     if-no-changes: "warn"         # "warn" (default), "error", or "ignore"
@@ -47,6 +47,8 @@ safe-outputs:
     github-token: ${{ secrets.SOME_CUSTOM_TOKEN }} # optional custom token for permissions
 ```
 
+The `draft` field is a **configuration policy**, not a default. Whatever value is set in the workflow frontmatter is always used — the agent cannot override it at runtime.
+
 PR creation may fail if "Allow GitHub Actions to create and approve pull requests" is disabled in Organization Settings. By default (`fallback-as-issue: true`), fallback creates an issue with branch link and requires `issues: write` permission. Set `fallback-as-issue: false` to disable fallback and only require `contents: write` + `pull-requests: write`.
 
 When `create-pull-request` is configured, git commands (`checkout`, `branch`, `switch`, `add`, `rm`, `commit`, `merge`) are automatically enabled.
@@ -78,6 +80,25 @@ When `push-to-pull-request-branch` is configured, git commands (`checkout`, `bra
 
 Like `create-pull-request`, pushes with GitHub Agentic Workflows do not trigger CI. See [Triggering CI](/gh-aw/reference/triggering-ci/) for how to enable automatic CI triggers.
 
+### Compile-Time Warnings for `target: "*"`
+
+When `target: "*"` is used, `gh aw compile` emits warnings for two common misconfigurations:
+
+- **Missing wildcard fetch** — no `checkout` block with a wildcard `fetch` pattern (e.g., `fetch: ["*"]`). Without this, the agent cannot access arbitrary PR branches at runtime and will fail with permission-like errors.
+- **No constraints** — neither `title-prefix` nor `labels` is set, which allows pushing to any PR in the repository with no additional gating.
+
+Both warnings are suppressed when the recommended configuration is in place:
+
+```yaml wrap
+safe-outputs:
+  push-to-pull-request-branch:
+    target: "*"
+    title-prefix: "[bot] "
+checkout:
+  fetch: ["*"]
+  fetch-depth: 0
+```
+
 ### Fail-Fast on Code Push Failure
 
 If `push-to-pull-request-branch` (or `create-pull-request`) fails, the safe-output pipeline cancels all remaining non-code-push outputs. Each cancelled output is marked with an explicit reason such as "Cancelled: code push operation failed". The failure details appear in the agent failure issue or comment generated by the conclusion job.
diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
index 2081c12470d..0808cf8690d 100644
--- a/docs/src/content/docs/reference/tools.md
+++ b/docs/src/content/docs/reference/tools.md
@@ -64,6 +64,8 @@ tools:
 
 **Note:** Some engines require third-party Model Context Protocol (MCP) servers for web search. See [Using Web Search](/gh-aw/guides/web-search/).
 
+For the **Codex** engine, `web-search:` is disabled by default. Web search is only enabled when `web-search:` is explicitly declared in the `tools:` block. Without this declaration, Codex runs with `--no-search` and cannot access the web.
+
 ### Playwright Tool (`playwright:`)
 
 Configure Playwright for browser automation and testing:
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index e645c15a2b2..03b7aa139f1 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -12,7 +12,8 @@ The `gh aw` CLI extension enables developers to create, manage, and execute AI-p
 | Command | Description |
 |---------|-------------|
 | [`gh aw init`](#init) | Set up your repository for agentic workflows |
-| [`gh aw add`](#add) | Add workflows from other repositories |
+| [`gh aw add-wizard`](#add-wizard) | Add workflows with interactive guided setup |
+| [`gh aw add`](#add) | Add workflows from other repositories (non-interactive) |
 | [`gh aw compile`](#compile) | Convert markdown to GitHub Actions YAML |
 | [`gh aw list`](#list) | Quick listing of all workflows |
 | [`gh aw run`](#run) | Execute workflows immediately in GitHub Actions |
@@ -108,6 +109,18 @@ gh aw init --create-pull-request        # Initialize and open a pull request
 
 **Options:** `--no-mcp`, `--codespaces`, `--completions`, `--create-pull-request`
 
+#### `add-wizard`
+
+Add a workflow with interactive guided setup. Checks requirements, adds the markdown file, and generates the compiled YAML. Prompts for missing API keys and secrets.
+
+```bash wrap
+gh aw add-wizard githubnext/agentics/ci-doctor           # Interactive setup
+gh aw add-wizard https://github.com/org/repo/blob/main/workflows/my-workflow.md
+gh aw add-wizard githubnext/agentics/ci-doctor --skip-secret  # Skip secret prompt
+```
+
+**Options:** `--skip-secret` (bypass the API key prompt when the secret is already configured at org or repo level)
+
 #### `add`
 
 Add workflows from The Agentics collection or other repositories to `.github/workflows`.
