@@ -17,23 +17,28 @@ For Route 1, prefer MCP tools for straightforward tasks. Only invoke the `apify-
 
 ## MCP vs CLI selection
 
-Route 1 (use existing Actors: search, fetch details, run, get results, look up docs) is exposed through **two interchangeable transports**: the Apify MCP server and the Apify CLI. Routes 2 and 3 are CLI-only or SDK-only by nature and are unaffected by this section.
+Route 1 (use existing Actors: search, fetch details, run, get results, look up docs) is exposed through **two transports**: the Apify MCP server and the Apify CLI. They are usually interchangeable, but not always — an unauthenticated MCP server can search Actors without being able to run them (see Detection). Routes 2 and 3 are CLI-only or SDK-only by nature and are unaffected by this section.
 
 Detect available transports **once** at the start of the conversation and reuse the result for every Route 1 operation. Skills downstream (`apify-ultimate-scraper`, etc.) provide both MCP and CLI variants per step — they will not re-detect.
 
 ### Detection
 
-1. **MCP available** if a tool named `search-actors` appears in your available tool list. (Other Apify MCP tools — `fetch-actor-details`, `run-actor`, `get-dataset-items`, `search-apify-docs`, `fetch-apify-docs` — are part of the same server.)
-2. **CLI available** if `apify --help` exits 0 in the shell.
+MCP state — judge by capability, not tool names:
+- **full**: run Actors and tasks, read datasets and key-value stores, search Actors, fetch Actor details, search and fetch docs
+- **discovery-only**: search Actors, fetch Actor details, search and fetch docs only (not authenticated)
+- **none**: no Apify MCP tools present
+
+CLI: **installed** if `apify --help` exits 0; **usable** if `apify info 2>&1` also exits 0.
 
 ### Selection rule
 
 | MCP | CLI | Use for Route 1 |
 |-----|-----|-----------------|
-| yes | yes | **MCP** (no shell, no install friction, OAuth handles auth) |
-| yes | no  | MCP |
-| no  | yes | CLI |
-| no  | no  | Offer to install the CLI (`npm install -g apify-cli`) or point the user to a host that ships the Apify MCP server (`https://mcp.apify.com`). Do not attempt Route 1 until one is available. |
+| full | any | **MCP** (no shell, no install friction, auth is handled by the host) |
+| discovery-only | usable | **MCP for discovery, CLI for runs and results** |
+| discovery-only | not usable | Discovery over MCP. For anything authenticated there is **no transport** — report that, and see Authentication for the fix |
+| none | usable | CLI |
+| none | not usable | Offer to install the CLI (`npm install -g apify-cli`) or point the user to a host that ships the Apify MCP server (`https://mcp.apify.com`). Do not attempt Route 1 until one is available. |
 
 Route 2 always requires the CLI regardless of MCP availability — `apify init`, `apify run`, and `apify push` operate on the local filesystem and have no MCP equivalent. Route 3 uses the `apify-client` package over HTTPS and needs neither.
 
@@ -47,16 +52,19 @@ State the chosen transport once when you start a Route 1 task ("Using MCP for th
 
 Three auth flows exist. Use the correct one based on the route:
 
-- **Route 1 (MCP):** OAuth. No setup needed. The user will be prompted to sign in via browser on first MCP tool call that requires auth. Do not ask for an API token.
-- **Route 1 (CLI fallback) and Route 2 (CLI):** The CLI **ignores** the `APIFY_TOKEN` env var. Run `apify login --token TOKEN` once (requires `required_permissions: ["all"]` in Cursor). Credentials are stored in `~/.apify/auth.json` and reused automatically. Token from: https://console.apify.com/settings/integrations
+- **Route 1 (MCP):** If your Apify MCP tools already cover authenticated operations, auth is working — say nothing. OAuth is the preferred auth method, but if the host does not support it, direct the user to set `APIFY_TOKEN`. Token from: https://console.apify.com/settings/integrations
+- **Route 1 (CLI fallback) and Route 2 (CLI):** Prefer `apify login` (opens browser) — credentials persist in `~/.apify/auth.json`. In headless environments, the CLI also reads `APIFY_TOKEN` from the environment automatically. Token from: https://console.apify.com/settings/integrations
 - **Route 3 (SDK):** Requires `APIFY_TOKEN` environment variable. Direct the user to **Console > Settings > Integrations** at https://console.apify.com/settings/integrations to create one. If they don't have an account, point them to https://console.apify.com/sign-up (free, no credit card).
 
 ### Apify CLI instructions:
-- Before using the CLI, always check if it is installed (always check first, with short `block_until_ms` to avoid blocking the conversation):
+**Rule: pass `--user-agent apify-opencode-plugin/apify` only on actor start and actor run commands (`apify actors start`, `apify actors call`). Do not add it to login, info, or other CLI commands.**
+
+- Before using the CLI, always check if it is installed. Keep the timeout short so the check cannot stall the conversation:
     ```bash
     apify --help
+    apify --version # The flag needs Apify CLI 1.5.0 or newer
     ```
-- If the CLI is installed, check if it is logged in (always check, with short `block_until_ms` to avoid blocking the conversation):
+- If the CLI is installed, check if it is logged in.  Keep the timeout short so the check cannot stall the conversation:
     ```bash
     # Auth check — do NOT pipe to /dev/null, you need to see errors
     apify info 2>&1
@@ -65,15 +73,15 @@ Three auth flows exist. Use the correct one based on the route:
     ```bash
     apify login --token TOKEN
     ```
-- All of the APify commands needs to be run with the all permissions (depends on Agent sandbox)
-- Apify commands blocks with **zero output** until the run completes. Set `block_until_ms` to at least **60000** (60s).
+- Authenticated Apify CLI commands need file access to `~/.apify/`, where the CLI keeps its credentials. A host that sandboxes file access can deny this even when the login is valid — that is a sandbox problem, not a login problem, so re-running `apify login` will not fix it. Grant the CLI file access in whatever way the host offers, or authenticate MCP and run through it instead.
+- Apify commands block with **zero output** until the run completes, so allow at least **60 seconds** before treating one as stuck. If your shell tool takes a timeout, raise it accordingly.
 - For long/unknown runs, use the async pattern instead:
     ```bash
-    apify actors start "ACTOR_ID" -i 'JSON_INPUT' --json 2>/dev/null
+    apify actors start "ACTOR_ID" -i 'JSON_INPUT' --user-agent apify-opencode-plugin/apify --json 2>/dev/null
     ```
-Then poll with `apify info`:
+Then poll with `apify runs info`:
     ```bash
-    apify info actor-runs/RUN_ID --json
+    apify runs info RUN_ID --json
     ```
 Check `.status` for `SUCCEEDED` or `FAILED`.
 ## Resources
 
@@ -10,7 +10,7 @@ Do **not**:
 
 - Call any `apify-*` skill directly from the slash menu without going through the `apify` subagent.
 - Guess between `apify-actor-development` vs `apify-actorization` vs `apify-sdk-integration` yourself — the subagent owns that decision (the `apify` SDK package and the `apify-client` package are easy to confuse and picking wrong breaks the user's project).
-- Skip the subagent for "quick" Apify questions. Even MCP tool calls (`search-actors`, `run-actor`, etc.) are routed through the subagent.
+- Skip the subagent for "quick" Apify questions. Even direct Apify MCP tool calls are routed through the subagent.
 
 If the user types a slash command for an Apify skill explicitly, still hand off to the `apify` subagent so the routing matrix and authentication guidance are applied.
 
@@ -19,9 +19,12 @@ If the user types a slash command for an Apify skill explicitly, still hand off
 Apify exposes three very different products through its plugin: (1) using existing Actors via MCP, (2) building and deploying custom Actors with the SDK + CLI, and (3) calling Actors from an existing application via `apify-client`. Each path requires a different skill, a different authentication flow, and a different npm package. The `apify` subagent is the only place where the routing matrix and the package-naming trap are documented, so every Apify request must pass through it.
 
 ### Apify CLI instructions:
-- Before using the CLI, always check if it is installed:
+**Rule: pass `--user-agent apify-opencode-plugin/apify-routing` only on actor start and actor run commands (`apify actors start`, `apify actors call`). Do not add it to login, info, or other CLI commands.**
+
+- Before using the CLI, always check if it is installed and new enough for the user-agent flag:
 ```bash
     apify --help
+    apify --version # The flag needs Apify CLI 1.5.0 or newer
 ```
 - If the CLI is installed, check if it is logged in:
 ```bash
@@ -32,14 +35,15 @@ Apify exposes three very different products through its plugin: (1) using existi
 ```bash
     apify login --token TOKEN
 ```
-- All of the APify commands needs to be run with the all permissions (depends on Agent sandbox)
-- Apify commands blocks with **zero output** until the run completes. Set `block_until_ms` to at least **60000** (60s).
+- In headless environments where browser login is unavailable, the CLI also reads `APIFY_TOKEN` from the environment automatically — no explicit login needed.
+- Authenticated Apify CLI commands need file access to `~/.apify/`, where the CLI keeps its credentials. A host that sandboxes file access can deny this even when the login is valid — that is a sandbox problem, not a login problem, so re-running `apify login` will not fix it.
+- Apify commands block with **zero output** until the run completes, so allow at least **60 seconds** before treating one as stuck. If your shell tool takes a timeout, raise it accordingly.
 - For long/unknown runs, use the async pattern instead:
 ```bash
-    apify actors start "ACTOR_ID" -i 'JSON_INPUT' --json 2>/dev/null
+    apify actors start "ACTOR_ID" -i 'JSON_INPUT' --user-agent apify-opencode-plugin/apify-routing --json 2>/dev/null
 ```
-Then poll with `apify info`:
+Then poll with `apify runs info`:
 ```bash
-    apify info actor-runs/RUN_ID --json
+    apify runs info RUN_ID --json
 ```
 Check `.status` for `SUCCEEDED` or `FAILED`.
@@ -22,6 +22,8 @@ Actors are serverless programs inspired by the UNIX philosophy - programs that d
 
 Before creating or modifying actors, verify that `apify` CLI is installed `apify --help`.
 
+**Rule: pass `--user-agent apify-opencode-plugin/apify-actor-development` only on actor run commands (`apify run`). Do not add it to login, info, push, or other CLI commands.**
+
 If it is not installed, use one of these methods (listed in order of preference):
 
 ```bash
@@ -131,10 +133,10 @@ Check `usesStandbyMode` in `.actor/actor.json` - only implement if set to `true`
 ## Commands
 
 ```bash
-apify run          # Run Actor locally
-apify login        # Authenticate account
-apify push         # Deploy to Apify platform (uses name from .actor/actor.json)
-apify help         # List all commands
+apify run --user-agent apify-opencode-plugin/apify-actor-development     # Run Actor locally
+apify login   # Authenticate account
+apify push    # Deploy to Apify platform (uses name from .actor/actor.json)
+apify help                                          # List all commands
 ```
 
 **IMPORTANT:** Always use `apify run` to test actors locally. Do not use `npm run start`, `npm start`, `yarn start`, or other package manager commands - these will not properly configure the Apify environment and storage.
 
@@ -24,10 +24,13 @@ Actorization converts existing software into reusable serverless applications co
 
 ## Prerequisites
 
-Verify `apify` CLI is installed:
+**Rule: pass `--user-agent apify-opencode-plugin/apify-actorization` only on actor run commands (`apify run`). Do not add it to login, info, init, push, or other CLI commands.**
+
+Verify `apify` CLI is installed and new enough for the user-agent flag:
 
 ```bash
 apify --help
+apify --version # The flag needs Apify CLI 1.5.0 or newer
 ```
 
 If not installed, use one of these methods (listed in order of preference):
@@ -139,13 +142,13 @@ See the Actor README guidelines at `skills/apify-actor-development/references/ac
 Run the actor with inline input (for JS/TS and Python actors):
 
 ```bash
-apify run --input '{"startUrl": "https://example.com", "maxItems": 10}'
+apify run --user-agent apify-opencode-plugin/apify-actorization --input '{"startUrl": "https://example.com", "maxItems": 10}'
 ```
 
 Or use an input file:
 
 ```bash
-apify run --input-file ./test-input.json
+apify run --user-agent apify-opencode-plugin/apify-actorization --input-file ./test-input.json
 ```
 
 **Important:** Always use `apify run`, not `npm start` or `python main.py`. The CLI sets up the proper environment and storage.
 
@@ -13,9 +13,11 @@ This rule does **not** apply to status/auth commands (`apify info`, `apify --ver
 
 **Exception:** if `--input` returns no data, re-run with `2>&1` to confirm whether the cause is a missing schema vs. a network/auth error.
 
+**Rule: pass `--user-agent apify-opencode-plugin/apify-ultimate-scraper` only on actor start and actor run commands (`apify actors start`, `apify actors call`). Do not add it to login, info, search, or other CLI commands.**
+
 ## Prerequisites
 
-- Apify CLI v1.4.0+ (`npm install -g apify-cli`)
+- Apify CLI v1.5.0+ (`npm install -g apify-cli`) — older versions reject the user-agent flag
 - Authenticated session (see below)
 
 ## Authentication
@@ -34,9 +36,10 @@ Generate token: https://console.apify.com/settings/integrations
 
 Before using the Apify CLI, always verify the local environment:
 
-1. Check that the CLI is installed:
+1. Check that the CLI is installed and is v1.5.0 or newer:
 ```bash
     apify --help
+    apify --version
 ```
 If this fails, install the CLI first:
 ```bash
@@ -54,20 +57,20 @@ If this fails, install the CLI first:
     apify login --token TOKEN
 ```
 
-3. Run Apify CLI commands with `all` permissions when needed by the agent sandbox.
+3. Authenticated Apify CLI commands need file access to `~/.apify/`, where the CLI keeps its credentials. A host that sandboxes file access can deny this even when the login is valid; that is a sandbox problem, not a login problem.
 
-4. Assume many Apify commands block with zero output until completion. For blocking runs, set `block_until_ms` to at least `60000`.
+4. Assume many Apify commands block with zero output until completion, so allow at least 60 seconds before treating one as stuck. If your shell tool takes a timeout, raise it accordingly.
 
 5. For long or unknown-duration runs, prefer the async pattern:
 
 ```bash
-    apify actors start "ACTOR_ID" -i 'JSON_INPUT' --json 2>/dev/null
+    apify actors start "ACTOR_ID" -i 'JSON_INPUT' --user-agent apify-opencode-plugin/apify-ultimate-scraper --json 2>/dev/null
 ```
 
    Then poll the run status:
 
 ```bash
-    apify info actor-runs/RUN_ID --json
+    apify runs info RUN_ID --json
 ```
 
    Check `.status` for `SUCCEEDED` or `FAILED`.
@@ -143,7 +146,7 @@ Before starting the run, double-check whether the task is short enough for a blo
 
 **Standard run (blocking):**
 ```bash
-    apify actors call "ACTOR_ID" -i 'JSON_INPUT' --json 2>/dev/null
+    apify actors call "ACTOR_ID" -i 'JSON_INPUT' --user-agent apify-opencode-plugin/apify-ultimate-scraper --json 2>/dev/null
 ```
 From output: `.id` (run ID), `.status`, `.defaultDatasetId`, `.stats.durationMillis`
 
@@ -159,9 +162,9 @@ For CSV: `apify datasets get-items DATASET_ID --format csv`
 
 **Large/long-running scrapes:**
 ```bash
-    apify actors start "ACTOR_ID" -i 'JSON_INPUT' --json 2>/dev/null
+    apify actors start "ACTOR_ID" -i 'JSON_INPUT' --user-agent apify-opencode-plugin/apify-ultimate-scraper --json 2>/dev/null
 ```
-Poll: `apify info actor-runs/RUN_ID --json` (check `.status` for `SUCCEEDED` or `FAILED`).
+Poll: `apify runs info RUN_ID --json` (check `.status` for `SUCCEEDED` or `FAILED`).
 
 ### Step 4: Deliver results