fix: align Cursor plugin workflows with CLI 0.9.3

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "parallel",
   "displayName": "Parallel",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Web search, content extraction, deep research, data enrichment, entity discovery (FindAll), and web monitoring — powered by parallel-cli.",
   "author": {
     "name": "Parallel Web Systems",

README.md

@@ -1,95 +1,86 @@
-# Parallel — Cursor Plugin
+# Parallel Cursor Plugin
 
-Web search, content extraction, deep research, and data enrichment powered by [parallel-cli](https://docs.parallel.ai/home).
+Web search, content extraction, deep research, data enrichment, entity discovery and web monitoring powered by [parallel-cli](https://docs.parallel.ai/integrations/cli).
 
 ## Features
 
+This source package contains six skills, nine commands and one citation rule. Cursor's official marketplace reviews updates separately from GitHub changes, so the installed listing may contain an earlier revision. Check the listing and installed version before assuming source features have shipped.
+
 | Capability | Skill | Command |
-|---|---|---|
-| **Web Search** | `parallel-web-search` | `/parallel-search <query>` |
-| **Content Extraction** | `parallel-web-extract` | `/parallel-extract <url>` |
-| **Deep Research** | `parallel-deep-research` | `/parallel-research <topic>` |
-| **Data Enrichment** | `parallel-data-enrichment` | `/parallel-enrich <data>` |
-| **Entity Discovery** | `parallel-findall` | `/parallel-findall <objective>` |
-| **Web Monitoring** | `parallel-monitor` | `/parallel-monitor <action>` |
+| --- | --- | --- |
+| Web Search | `parallel-web-search` | `/parallel-search <query>` |
+| Content Extraction | `parallel-web-extract` | `/parallel-extract <url> [url2]` |
+| Deep Research | `parallel-deep-research` | `/parallel-research <topic>` |
+| Data Enrichment | `parallel-data-enrichment` | `/parallel-enrich <data>` |
+| Entity Discovery | `parallel-findall` | `/parallel-findall <objective>` |
+| Web Monitoring | `parallel-monitor` | `/parallel-monitor <action>` |
+
+Additional commands: `/parallel-setup`, `/parallel-status <run_id>` and `/parallel-result <run_id>`. Status and result are for research tasks only.
 
-Additional commands: `/parallel-setup`, `/parallel-status <run_id>`, `/parallel-result <run_id>`
+The package uses the authenticated CLI and does not bundle an MCP server. Ordinary lookups use Search with its default `basic` mode. Deep research requires an explicit request. FindAll discovers entities; enrichment adds fields to an existing list. Monitors persist until cancelled and can incur charges on scheduled or triggered executions.
 
 ## Installation
 
-1. Install the plugin in Cursor from the marketplace (or see [Local Development](#local-development) to test from source).
-2. Run `/parallel-setup` to install `parallel-cli` and authenticate.
+1. Install **Parallel** from Cursor's marketplace.
+2. Run `/parallel-setup` in Cursor to check CLI installation, feature support and authentication.
 
-### Manual CLI Setup
+For manual setup, prefer pipx:
 
 ```bash
-curl -fsSL https://parallel.ai/install.sh | bash
+pipx install "parallel-web-tools[cli]"
+pipx ensurepath
 parallel-cli login
 ```
 
-Or via pipx:
+If pipx is unavailable, the standalone installer is another option:
 
 ```bash
-pipx install "parallel-web-tools[cli]"
+curl -fsSL https://parallel.ai/install.sh | bash
 parallel-cli login
 ```
 
-## Quick Start
+This source package is checked against CLI 0.9.3. Monitor GA commands require ≥ 0.4.0, Entity Search ≥ 0.6.0, research text/context and enrichment suggestions ≥ 0.3.0, and optional Search `fast` ≥ 0.9.2. Upgrade through the original installation method using `/parallel-setup`, and verify the CLI in Cursor's terminal. Cursor and Parallel CLI versions are separate.
 
-**Search the web:**
-```
-/parallel-search latest developments in AI chip manufacturing
-```
+`PARALLEL_API_KEY` overrides stored login credentials. `/parallel-setup` checks the active credential source without exposing secrets; stored organization metadata does not identify an overriding environment key's organization.
 
-**Extract a webpage:**
-```
-/parallel-extract https://example.com/article
-```
+## Quick Start
 
-**Deep research (slower, more thorough):**
-```
+```text
+/parallel-search latest developments in AI chip manufacturing
+/parallel-extract https://docs.parallel.ai/integrations/cli https://docs.parallel.ai/integrations/cursor-marketplace
 /parallel-research comprehensive analysis of React vs Vue in 2026
-```
-
-**Enrich data:**
-```
 /parallel-enrich companies.csv with CEO name, funding amount, and headquarters
+/parallel-findall Find European climate-tech companies with headquarters and official homepage
+/parallel-monitor Watch for official Parallel API changelog announcements daily
 ```
 
-## Local Development
-
-To test the plugin locally without installing from the marketplace:
+Async research, enrichment and FindAll return IDs that should be saved before polling. Polling timeouts end the local wait; resume the saved job instead of submitting another. Research may produce JSON only or JSON plus Markdown. Async enrichment produces JSON; requested CSV is converted locally with failed rows retained. FindAll requested fields require verified enrichment output, and an Entity Search ID cannot be polled as a FindAll run.
 
-1. Clone this repo:
-   ```bash
-   git clone https://github.com/parallel-web/parallel-cursor-plugin.git
-   ```
+Monitor setup must follow the user's requested schedule and notification destination. A CLI polling loop does not guarantee future notifications. Save its monitor ID, inspect events and completion history, and cancel it when monitoring is no longer wanted.
 
-2. Open the repo in Cursor:
-   ```bash
-   cursor parallel-cursor-plugin
-   ```
+## Local Development
 
-3. Skills and rules are auto-discovered from the standard directories. Type `/` in the chat to verify the `parallel-*` skills are listed.
+Follow [Cursor's plugin documentation](https://cursor.com/docs/plugins) and [manifest reference](https://cursor.com/docs/reference/plugins). Test in a disposable Cursor environment so existing installs and work are preserved.
 
-4. Commands are **not** auto-discovered when testing locally. Symlink them into Cursor's project commands directory:
-   ```bash
-   ln -s ../commands .cursor/commands
-   ```
+1. Clone this repository.
+2. Confirm `~/.cursor/plugins/local/parallel` is absent before copying. If it exists, inspect its ownership and contents rather than overwriting it.
+3. Copy the real package directory under that path, including `.cursor-plugin/plugin.json`, `skills`, `commands` and `rules`. Exclude `.git` and planning artifacts. Symlinks outside the local plugin directory are skipped.
+4. Reload the disposable Cursor window. Inspect Customize for package origin, all six skills, nine commands and citation rule at the intended user or project scope.
+5. Check that slash commands invoke their corresponding skills. Then use `/parallel-setup` to verify the terminal's CLI and credential source before an authorized capability test.
 
-5. Type `/` again — the `parallel-*` commands should now appear alongside the skills.
+A same-name marketplace plugin takes precedence over the local copy. Test with that conflict absent only in the disposable environment. Enterprise policy can block local imports; do not change policy to force a test. Opening this repository or adding project-command symlinks does not prove plugin loading.
 
-6. Run `/parallel-setup` to confirm the CLI is installed and authenticated.
+Verify each intended consumer independently, including the IDE, Agents Window and any Cursor CLI workflow. This source update does not establish propagation to cloud agents, Grok or Slack. Local loading and an upgrade rehearsal do not prove an official marketplace update or an existing marketplace install's upgrade.
 
 ## Plugin Structure
 
-```
+```text
 .cursor-plugin/plugin.json   Plugin manifest
-skills/                       4 skills (auto-discovered)
-commands/                     7 slash commands
-rules/                        Citation standards rule
+skills/                      6 capability skills
+commands/                    9 slash commands
+rules/                       1 citation standards rule
 ```
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

commands/parallel-result.md

@@ -1,16 +1,24 @@
 ---
 name: parallel-result
-description: "Get completed research task result. Usage: /parallel-result <run_id>"
+description: "Retrieve research task output only. Usage: /parallel-result <run_id>"
 ---
 
 # Get Research Result
 
 ## Run ID: $ARGUMENTS
 
+Use only a saved research `run_id`. Establish an unknown ID's origin first. For enrichment use `enrich poll`, for FindAll use `findall poll` or `findall result`, and for Monitor use `monitor events`. Never poll an Entity Search ID or Search/Extract session ID as research.
+
+Choose a concrete, run-specific output base in a persistent directory, such as `reports/research-<run-id>`. Create the parent directory if needed and inspect existing `.json` and `.md` paths. Replace `$OUTPUT_BASE` below with that chosen base.
+
 ```bash
-parallel-cli research poll "$ARGUMENTS" --json
+parallel-cli research poll "$ARGUMENTS" --timeout 60 -o "$OUTPUT_BASE"
 ```
 
-Present results in a clear, organized format.
+Do not add `--json` or dump the full output into chat. On completion, JSON contains metadata and basis; Markdown exists only for text output. In that case, resolve `output.content_file` relative to the saved JSON. Read the actual saved paths and verify files exist before linking them. The CLI can fall back to temporary storage after a write error; inspect partial writes and copy the final files to the intended persistent location before claiming durable delivery.
+
+Existing files are refused unless `--force` is explicit. Prefer a fresh base, and use `--force` only when replacing those files is intended. Share an executive summary if printed; otherwise summarize only inspected relevant output. Report the actual paths and retain the returned `interaction_id` for Task follow-ups.
+
+Timeout exit 5 or interruption ends the local wait. Check the same saved task with `/parallel-status`, then resume this poll for a pending/running task. Retrieve completed output or report failed/cancelled/`action_required` states; never submit a replacement task because polling ended.
 
-If CLI not found, tell user to run `/parallel-setup`.
+If the binary is missing, use `/parallel-setup`. For a missing command or option, use its installation-specific upgrade guidance. For authentication errors, inspect `parallel-cli auth --json` and `authenticated`; a `403` alone does not prove insufficient balance.

commands/parallel-setup.md

@@ -5,68 +5,64 @@ description: Set up the Parallel plugin (install CLI and authenticate)
 
 # Parallel Plugin Setup
 
-## Step 1: Check if CLI is already installed
+## Check the CLI in Cursor's terminal
 
 ```bash
 parallel-cli --version
 ```
 
-If this prints a version, skip to **Step 2: Authenticate**.
-
-## Step 1b: Attempt installation
-
-Try installing with the install script:
+If the binary exists, check the help for the feature the user needs before skipping installation. This package is checked against CLI 0.9.3. Monitor's GA commands require ≥ 0.4.0, Entity Search ≥ 0.6.0, research text/context and enrichment suggestions ≥ 0.3.0, and optional native Search `fast` ≥ 0.9.2. Default Search remains `basic`.
 
 ```bash
-curl -fsSL https://parallel.ai/install.sh | bash
+parallel-cli monitor --help
+parallel-cli findall entity-search --help
+parallel-cli research run --help
+parallel-cli search --help
 ```
 
-If that fails, try pipx:
+`No such command`, `No such option` or `unrecognized arguments` indicates a stale or mismatched CLI interface. API, authentication and invalid-input errors do not indicate a version problem. Identify the install method before upgrading:
+
+| Install method | Upgrade |
+| --- | --- |
+| pipx | `pipx upgrade parallel-web-tools` |
+| uv tool | `uv tool upgrade parallel-web-tools` |
+| Homebrew | `brew upgrade parallel-web/tap/parallel-cli` |
+| npm global | `npm update -g parallel-web-cli` |
+| Standalone install script | `parallel-cli update` |
+
+Recheck version and feature help in the same Cursor terminal after upgrading. Do not use the standalone updater for a package-manager install.
+
+## Install when the binary is missing
+
+Prefer pipx for an isolated Python CLI installation:
 
 ```bash
 pipx install "parallel-web-tools[cli]"
 pipx ensurepath
 ```
 
-After either install method, verify it worked:
+If pipx is unavailable, use the documented standalone installer in a terminal with the required network and filesystem access:
 
 ```bash
-parallel-cli --version
-```
-
-### If installation fails
-
-Tell the user to re-run `/parallel-setup` with sandbox mode disabled. Installation requires network and filesystem access that Cursor's sandbox may block.
-
-Alternatively, they can install manually in their own terminal:
-
-```
 curl -fsSL https://parallel.ai/install.sh | bash
 ```
 
-or:
-
-```
-pipx install "parallel-web-tools[cli]"
-pipx ensurepath
-```
-
-They may need to add `~/.local/bin` to PATH in their shell config (e.g. `~/.zshrc`). Ask them to re-run `/parallel-setup` once installed.
-
-## Step 2: Authenticate
+If an agent sandbox blocks installation, explain the specific error and give the user the appropriate terminal command. Do not tell them to disable sandboxing. Verify `parallel-cli --version` in Cursor's terminal; a successful install in another shell does not establish this terminal's PATH. If needed, add the actual installation bin directory (commonly `~/.local/bin`) to the shell PATH and open a new terminal.
 
-Check if already authenticated:
+## Check authentication and active credential source
 
 ```bash
-parallel-cli auth
+parallel-cli auth --json
 ```
 
-If not authenticated, tell the user to run `parallel-cli login` in their terminal, or set `PARALLEL_API_KEY` in their environment.
+Inspect `authenticated`, `method`, `env_var_set` and `has_stored_credentials`. Exit zero alone is not success: this command also exits zero with `authenticated: false`. Authentication status reports available credentials; it does not validate API access, credit or account policy.
 
-## Step 3: Verify
+If `authenticated` is false, tell the user to run `parallel-cli login` in their terminal or set `PARALLEL_API_KEY` in the environment inherited by Cursor. Never request or print credentials in chat.
 
-```bash
-parallel-cli auth
-```
+If `method` is `environment`, `PARALLEL_API_KEY` overrides stored login. Any `selected_org_id` or `selected_org_name` describes the inactive stored login, not the environment key's organization. Report that distinction. The environment key's billing organization must be verified independently before an account-specific or paid test; do not claim that it belongs to the stored organization. Do not switch accounts or remove overrides automatically.
+
+If `method` is `oauth`, selected organization metadata describes the active stored login. Report only nonsecret account metadata needed for the request.
+
+## Verify readiness
 
-Confirm the CLI is installed, authenticated, and ready to use.
+Repeat `parallel-cli auth --json` in the agent's terminal and confirm the binary, required feature help and `authenticated` boolean. State the active credential source and any unverified organization or API-access limitation. Do not start a paid job or add funds merely to prove setup. For a `403`, inspect the actual permissions, policy or billing error before suggesting a remedy.

commands/parallel-status.md

@@ -1,14 +1,18 @@
 ---
 name: parallel-status
-description: "Check running research task status. Usage: /parallel-status <run_id>"
+description: "Check research task status only. Usage: /parallel-status <run_id>"
 ---
 
 # Check Research Status
 
 ## Run ID: $ARGUMENTS
 
+Use only a saved research `run_id`. If the ID's origin is unknown, establish which operation returned it before calling the CLI. Enrichment task groups use `enrich status`, FindAll runs use `findall status`, and monitors use `monitor get`. Entity Search IDs and Search/Extract session IDs cannot be checked as research tasks.
+
 ```bash
 parallel-cli research status "$ARGUMENTS" --json
 ```
 
-If CLI not found, tell user to run `/parallel-setup`.
+Inspect the exit status and JSON. Report pending/running, completed, failed/cancelled or `action_required` accurately. On failure, preserve the run ID and report the returned error; do not create a new research task. An `action_required` state needs the indicated action, not indefinite polling. Use `/parallel-result` to retrieve completed output.
+
+If the binary is missing, use `/parallel-setup`. For a missing command or option, use its installation-specific upgrade guidance. For authentication errors, inspect `parallel-cli auth --json` and `authenticated`; a `403` alone does not prove insufficient balance.

rules/citation-standards.mdc

@@ -24,10 +24,12 @@ When presenting information from web search results:
 
 **End every search response with a Sources section** listing all referenced URLs:
 
-```
+```text
 Sources:
 - [Source Title](https://example.com/article) (Feb 2026)
 - [Another Source](https://example.com/other) (Jan 2026)
 ```
 
 This Sources section is mandatory. Do not omit it.
+
+Include source dates only when returned or verified in retrieved content. Omit unknown dates rather than guessing them.