docs: tighten Parallel CLI skill guidance

Clarify that Parallel is an optional paid vendor workflow, add headless auth and context-chaining guidance, and align command examples more closely with upstream docs before salvaging PR #985.

skills/research/parallel-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: parallel-cli
-description: Use Parallel CLI for agent-native web search, content extraction, deep research, enrichment, FindAll entity discovery, and monitoring. Prefer JSON output and non-interactive flows.
+description: Optional vendor skill for Parallel CLI — agent-native web search, extraction, deep research, enrichment, FindAll, and monitoring. Prefer JSON output and non-interactive flows.
-version: 1.0.0
+version: 1.1.0
 author: Hermes Agent
 license: MIT
 metadata:
@@ -12,48 +12,61 @@ metadata:
 
 # Parallel CLI
 
-Use `parallel-cli` when the user wants Parallel specifically, or when a terminal-native workflow would benefit from Parallel's web search, extraction, deep research, or enrichment stack.
+Use `parallel-cli` when the user explicitly wants Parallel, or when a terminal-native workflow would benefit from Parallel's vendor-specific stack for web search, extraction, deep research, enrichment, entity discovery, or monitoring.
+
+This is an optional third-party workflow, not a Hermes core capability.
+
+Important expectations:
+- Parallel is a paid service with a free tier, not a fully free local tool.
+- It overlaps with Hermes native `web_search` / `web_extract`, so do not prefer it by default for ordinary lookups.
+- Prefer this skill when the user mentions Parallel specifically or needs capabilities like Parallel's enrichment, FindAll, or monitor workflows.
 
 `parallel-cli` is designed for agents:
 - JSON output via `--json`
 - Non-interactive command execution
 - Async long-running jobs with `--no-wait`, `status`, and `poll`
+- Context chaining with `--previous-interaction-id`
 - Search, extract, research, enrichment, entity discovery, and monitoring in one CLI
 
 ## When to use it
 
 Prefer this skill when:
 - The user explicitly mentions Parallel or `parallel-cli`
-- The task needs richer workflows than a simple web search/extract pass
+- The task needs richer workflows than a simple one-shot search/extract pass
 - You need async deep research jobs that can be launched and polled later
-- You need structured data enrichment, FindAll, or monitoring capabilities
+- You need structured enrichment, FindAll entity discovery, or monitoring
 
 Prefer Hermes native `web_search` / `web_extract` for quick one-off lookups when Parallel is not specifically requested.
 
 ## Installation
 
-Try the fastest install path available for the environment.
+Try the least invasive install path available for the environment.
 
-### Standalone binary
+### Homebrew
-
-```bash
-# macOS / Linux
-curl -fsSL https://parallel.ai/install.sh | bash
-```
-
-Homebrew is also supported:
 
 ```bash
 brew install parallel-web/tap/parallel-cli
 ```
 
-npm downloads the prebuilt binary:
+### npm
 
 ```bash
 npm install -g parallel-web-cli
 ```
 
-### Python fallback
+### Python package
+
+```bash
+pip install "parallel-web-tools[cli]"
+```
+
+### Standalone installer
+
+```bash
+curl -fsSL https://parallel.ai/install.sh | bash
+```
+
+If you want an isolated Python install, `pipx` can also work:
 
 ```bash
 pipx install "parallel-web-tools[cli]"
@@ -68,28 +81,35 @@ Interactive login:
 parallel-cli login
 ```
 
-Headless / CI / agent usage:
+Headless / SSH / CI:
+
+```bash
+parallel-cli login --device
+```
+
+API key environment variable:
 
 ```bash
 export PARALLEL_API_KEY="***"
 ```
 
-Verify auth:
+Verify current auth status:
 
 ```bash
-parallel-cli auth --json
+parallel-cli auth
 ```
 
 If auth requires browser interaction, run with `pty=true`.
 
 ## Core rule set
 
-1. Always prefer `--json` so Hermes can parse structured output.
+1. Always prefer `--json` when you need machine-readable output.
-2. Prefer non-interactive flags and explicit arguments.
+2. Prefer explicit arguments and non-interactive flows.
 3. For long-running jobs, use `--no-wait` and then `status` / `poll`.
 4. Cite only URLs returned by the CLI output.
 5. Save large JSON outputs to a temp file when follow-up questions are likely.
 6. Use background processes only for genuinely long-running workflows; otherwise run in foreground.
+7. Prefer Hermes native tools unless the user wants Parallel specifically or needs Parallel-only workflows.
 
 ## Quick reference
 
@@ -106,20 +126,42 @@ parallel-cli
 └── monitor create|list|get|update|delete|events|event-group|simulate
 ```
 
+## Common flags and patterns
+
+Commonly useful flags:
+- `--json` for structured output
+- `--no-wait` for async jobs
+- `--previous-interaction-id <id>` for follow-up tasks that reuse earlier context
+- `--max-results <n>` for search result count
+- `--mode one-shot|agentic` for search behavior
+- `--include-domains domain1.com,domain2.com`
+- `--exclude-domains domain1.com,domain2.com`
+- `--after-date YYYY-MM-DD`
+
+Read from stdin when convenient:
+
+```bash
+echo "What is the latest funding for Anthropic?" | parallel-cli search - --json
+echo "Research question" | parallel-cli research run - --json
+```
+
 ## Search
 
 Use for current web lookups with structured results.
 
 ```bash
 parallel-cli search "What is Anthropic's latest AI model?" --json
-parallel-cli search -q "bitcoin price" --after-date 2026-01-01 --json
 parallel-cli search "SEC filings for Apple" --include-domains sec.gov --json
+parallel-cli search "bitcoin price" --after-date 2026-01-01 --max-results 10 --json
+parallel-cli search "latest browser benchmarks" --mode one-shot --json
+parallel-cli search "AI coding agent enterprise reviews" --mode agentic --json
 ```
 
-Useful flags:
+Useful constraints:
-- `-q` for supplemental keyword queries
+- `--include-domains` to narrow trusted sources
-- `--after-date YYYY-MM-DD` for recency
+- `--exclude-domains` to strip noisy domains
-- `--include-domains domain1.com,domain2.com` to constrain sources
+- `--after-date` for recency filtering
+- `--max-results` when you need broader coverage
 
 If you expect follow-up questions, save output:
 
@@ -141,6 +183,7 @@ Use to pull clean content or markdown from a URL.
 parallel-cli extract https://example.com --json
 parallel-cli extract https://company.com --objective "Find pricing info" --json
 parallel-cli extract https://example.com --full-content --json
+parallel-cli fetch https://example.com --json
 ```
 
 Use `--objective` when the page is broad and you only need one slice of information.
@@ -149,26 +192,50 @@ Use `--objective` when the page is broad and you only need one slice of informat
 
 Use for deeper multi-step research tasks that may take time.
 
+Common processor tiers:
+- `lite` / `base` for faster, cheaper passes
+- `core` / `pro` for more thorough synthesis
+- `ultra` for the heaviest research jobs
+
 ### Synchronous
 
 ```bash
-parallel-cli research run "Compare the leading AI coding agents by pricing, model support, and enterprise controls" --json
+parallel-cli research run \
+  "Compare the leading AI coding agents by pricing, model support, and enterprise controls" \
+  --processor core \
+  --json
 ```
 
 ### Async launch + poll
 
 ```bash
-parallel-cli research run "Compare the leading AI coding agents by pricing, model support, and enterprise controls" --no-wait --json
+parallel-cli research run \
+  "Compare the leading AI coding agents by pricing, model support, and enterprise controls" \
+  --processor ultra \
+  --no-wait \
+  --json
+
 parallel-cli research status trun_xxx --json
 parallel-cli research poll trun_xxx --json
 parallel-cli research processors --json
 ```
 
+### Context chaining / follow-up
+
+```bash
+parallel-cli research run "What are the top AI coding agents?" --json
+parallel-cli research run \
+  "What enterprise controls does the top-ranked one offer?" \
+  --previous-interaction-id trun_xxx \
+  --json
+```
+
 Recommended Hermes workflow:
 1. launch with `--no-wait --json`
 2. capture the returned run/task ID
 3. if the user wants to continue other work, keep moving
 4. later call `status` or `poll`
+5. summarize the final report with citations from the returned sources
 
 ## Enrichment
 
@@ -180,13 +247,22 @@ Use when the user has CSV/JSON/tabular inputs and wants additional columns infer
 parallel-cli enrich suggest "Find the CEO and annual revenue" --json
 ```
 
-### Plan config
+### Plan a config
 
 ```bash
 parallel-cli enrich plan -o config.yaml
 ```
 
-### Non-interactive run
+### Inline data
+
+```bash
+parallel-cli enrich run \
+  --data '[{"company": "Anthropic"}, {"company": "Mistral"}]' \
+  --intent "Find headquarters and employee count" \
+  --json
+```
+
+### Non-interactive file run
 
 ```bash
 parallel-cli enrich run \
@@ -197,6 +273,12 @@ parallel-cli enrich run \
   --intent "Find the CEO and annual revenue"
 ```
 
+### YAML config run
+
+```bash
+parallel-cli enrich run config.yaml
+```
+
 ### Status / polling
 
 ```bash
@@ -205,57 +287,41 @@ parallel-cli enrich poll <task_group_id> --json
 ```
 
 Use explicit JSON arrays for column definitions when operating non-interactively.
+Validate the output file before reporting success.
 
 ## FindAll
 
-Use for web-scale entity discovery when the user wants a set of entities matching natural-language criteria.
+Use for web-scale entity discovery when the user wants a discovered dataset rather than a short answer.
 
 ```bash
 parallel-cli findall run "Find AI coding agent startups with enterprise offerings" --json
+parallel-cli findall run "AI startups in healthcare" -n 25 --json
 parallel-cli findall status <run_id> --json
 parallel-cli findall poll <run_id> --json
 parallel-cli findall result <run_id> --json
 parallel-cli findall schema <run_id> --json
 ```
 
-This is a better fit than ordinary search when the user wants a discovered dataset rather than a short answer.
+This is a better fit than ordinary search when the user wants a discovered set of entities that can be reviewed, filtered, or enriched later.
 
 ## Monitor
 
 Use for ongoing change detection over time.
 
 ```bash
-parallel-cli monitor create --help
 parallel-cli monitor list --json
 parallel-cli monitor get <monitor_id> --json
 parallel-cli monitor events <monitor_id> --json
 parallel-cli monitor delete <monitor_id> --json
 ```
 
-Use this when the user wants recurring tracking of a page or source rather than a one-time fetch.
+Creation is usually the sensitive part because cadence and delivery matter:
-
-## Input patterns for agents
-
-Read from stdin when convenient:
 
 ```bash
-echo "What is the latest funding for Anthropic?" | parallel-cli search - --json
+parallel-cli monitor create --help
-echo "Research question" | parallel-cli research run - --json
 ```
 
-## Error handling and exit codes
+Use this when the user wants recurring tracking of a page or source rather than a one-time fetch.
-
-The CLI documents these exit codes:
-- `0` success
-- `2` bad input
-- `3` auth error
-- `4` API error
-- `5` timeout
-
-If you hit auth errors:
-1. check `parallel-cli auth --json`
-2. confirm `PARALLEL_API_KEY` or run `parallel-cli login`
-3. verify `parallel-cli` is on `PATH`
 
 ## Recommended Hermes usage patterns
 
@@ -282,6 +348,37 @@ If you hit auth errors:
 4. Poll for completion if needed
 5. Validate the output file before reporting success
 
+## Error handling and exit codes
+
+The CLI documents these exit codes:
+- `0` success
+- `2` bad input
+- `3` auth error
+- `4` API error
+- `5` timeout
+
+If you hit auth errors:
+1. check `parallel-cli auth`
+2. confirm `PARALLEL_API_KEY` or run `parallel-cli login` / `parallel-cli login --device`
+3. verify `parallel-cli` is on `PATH`
+
+## Maintenance
+
+Check current auth / install state:
+
+```bash
+parallel-cli auth
+parallel-cli --help
+```
+
+Update commands:
+
+```bash
+parallel-cli update
+pip install --upgrade parallel-web-tools
+parallel-cli config auto-update-check off
+```
+
 ## Pitfalls
 
 - Do not omit `--json` unless the user explicitly wants human-formatted output.
@@ -289,3 +386,5 @@ If you hit auth errors:
 - `login` may require PTY/browser interaction.
 - Prefer foreground execution for short tasks; do not overuse background processes.
 - For large result sets, save JSON to `/tmp/*.json` instead of stuffing everything into context.
+- Do not silently choose Parallel when Hermes native tools are already sufficient.
+- Remember this is a vendor workflow that usually requires account auth and paid usage beyond the free tier.