fix: align CLI skill instructions and Cursor sync

scripts/sync-to-cursor.py

@@ -7,10 +7,11 @@
 - Cursor skills replace the trailing "## Setup" section (which has full
   install commands inline) with a brief "## If `parallel-cli` is not
   found" stanza that delegates to the cursor /parallel-setup command
-- Cursor has 4 skills (search/extract/research/enrichment); setup/status/
-  result are slash commands in cursor, not skills, so they are skipped
-  by this sync. Skills new to agent-skills (findall, monitor) get both a
-  synced SKILL.md AND a freshly-generated command wrapper
+- Cursor has six CLI skills; setup/status/result are slash commands,
+  not skills, so they are skipped. Search/extract descriptions use the CLI
+  as the default because this package does not bundle the source's MCP.
+- Missing command wrappers are generated; existing wrappers and version
+  remain owned by the Cursor repository.
 
 Usage:
     python3 scripts/sync-to-cursor.py [--dry-run] [--cursor-repo PATH]
@@ -41,18 +42,34 @@
 # Frontmatter fields that only make sense in Claude Code agent-skills.
 CC_ONLY_FIELDS = {"user-invocable", "argument-hint", "context", "agent"}
 
+CURSOR_DESCRIPTIONS = {
+    "parallel-web-search": (
+        "CLI web search, the default for lookups, current information and research queries. "
+        "Save retrieved sources as JSON and cite them. Only use parallel-deep-research "
+        "when the user explicitly requests deep or exhaustive research."
+    ),
+    "parallel-web-extract": (
+        "CLI content extraction from one or more URLs, including webpages, articles and PDFs. "
+        "Save JSON, preserve successful content and report per-URL failures."
+    ),
+}
+
 # Replacement for the agent-skills "## Setup" trailing section.
 # Heading is intentionally specific to "binary not installed" so it doesn't
 # get conflated with the in-body "errors with `no such command`" guidance,
-# which covers a separate failure mode (stale CLI) and routes to
-# `parallel-cli update`, not `/parallel-setup`.
+# which covers a separate failure mode (stale CLI). Setup also explains
+# installation-method-specific upgrades and authentication recovery.
 CURSOR_SETUP_SECTION = """## If the `parallel-cli` binary is not installed
 
-If the shell reports `command not found: parallel-cli` (i.e. the binary itself is missing — distinct from a `No such command` error from a stale CLI, which the in-body guidance above covers), **stop immediately**. Do NOT search the web yourself, do NOT use any built-in search tools, and do NOT try to answer the query from your own knowledge. Instead, tell the user:
+If the shell reports `command not found: parallel-cli`, stop and tell the user to run `/parallel-setup`, then retry their request. Do not substitute built-in search, another provider or an answer from memory.
+
+### Command and authentication failures
 
-1. `parallel-cli` is not installed
-2. Run `/parallel-setup` to install it
-3. Then retry their request
+`No such command`, `No such option` or `unrecognized arguments` from an installed CLI indicate a stale or mismatched interface. Check its version and upgrade through its installation method using `/parallel-setup`; `parallel-cli update` is for standalone installs only. Verify the required command in the same Cursor terminal before retrying.
+
+For authentication errors, run `parallel-cli auth --json` and inspect `authenticated`; exit zero alone does not prove authentication. Use `/parallel-setup` for terminal login or environment-key guidance, without requesting credentials in chat. A `403` can be an authorization or billing error: report the actual error and do not assume insufficient balance or add funds automatically.
+
+For other API/input errors, report the error without calling it a version problem. Reuse saved run IDs to resume asynchronous work. After an ambiguous creation failure, resolve whether a job exists before retrying creation.
 """
 
 # Skill → cursor command wrapper config. Heading-label is the noun the
@@ -98,7 +115,9 @@
 
 
 def transform_frontmatter(fm: str) -> str:
-    """Drop CC-only fields. fm is the inner frontmatter, no leading/trailing ---."""
+    """Adapt platform fields and routing; retain all other source metadata."""
+    name_match = re.search(r"(?m)^name:\s*([^\s]+)", fm)
+    description = CURSOR_DESCRIPTIONS.get(name_match.group(1)) if name_match else None
     out: list[str] = []
     skip_continuation = False
     for line in fm.splitlines():
@@ -107,6 +126,10 @@ def transform_frontmatter(fm: str) -> str:
             skip_continuation = m.group(1) in CC_ONLY_FIELDS
             if skip_continuation:
                 continue
+            if m.group(1) == "description" and description is not None:
+                out.append(f"description: {json.dumps(description)}")
+                skip_continuation = True
+                continue
         elif skip_continuation and (line.startswith((" ", "\t")) or line.strip() == ""):
             # multi-line value continuation of a skipped field
             continue

skills/parallel-data-enrichment/SKILL.md

@@ -25,9 +25,9 @@ If the user gave a vague intent ("enrich these companies with useful info") and
 parallel-cli enrich suggest "Find CEO and recent funding info" --json
 ```
 
-The response is an envelope: `{title, processor, enriched_columns, warnings}`. Extract just the **`enriched_columns` array** (not the whole envelope) and pass it as the value of `--enriched-columns` on `enrich run`, **in place of `--intent`** — the two flags are alternative ways to specify what to enrich, not combined. If `suggest` returned a `processor`, pass it through explicitly via `--processor` on the `run` call (it's a tuned recommendation for the schema). Skip this whole section if the user already specified the fields they want.
+The response is an envelope: `{title, processor, enriched_columns, warnings}`. Extract just the **`enriched_columns` array** (not the whole envelope) and pass it as the value of `--enriched-columns` on `enrich run`, **in place of `--intent`**. These flags are alternative ways to specify what to enrich. If `suggest` returned a `processor`, pass it explicitly via `--processor` on the `run` call. Skip this section if the user already specified the fields they want.
 
-> `enrich suggest` requires `parallel-cli` ≥ 0.3.0. If it errors with anything resembling `no such command` / `No such command` / `unknown command`, **do not bail** — skip the suggestion step, fall through to step 1 with `--intent`, complete the run, and mention `parallel-cli update` (or `pipx upgrade parallel-web-tools`) in the final response so the user picks up the feature next time.
+> `enrich suggest` requires `parallel-cli` ≥ 0.3.0. If only that command is missing, skip the optional suggestion step and use `--intent` in step 1. Suggest an installation-specific upgrade from Setup. Do not classify authentication, API or invalid-input failures as an older CLI. An intent-based run itself requests a suggestion; explicit columns default to `core-fast`, while intent can select another processor unless `--processor` overrides it.
 
 ## Step 1: Start the enrichment
 
@@ -51,48 +51,56 @@ If this is a **follow-up** to a previous research task and you have its `interac
 parallel-cli enrich run --data '...' --intent "..." --target "output.csv" --no-wait --json --previous-interaction-id "$INTERACTION_ID"
 ```
 
-The enrichment will run with the full context of that prior research — so you can enrich entities discovered earlier without restating what was already found. Note: enrichment does **not** itself produce a new `interaction_id`, so you cannot chain a further follow-up off of an enrichment.
+This reuses the prior Task's context. Context chaining is unavailable for Zero Data Retention (ZDR) accounts, so omit the flag there and include the needed context explicitly. Enrichment does **not** return a new `interaction_id`; retain the prior Task ID for later follow-ups. A `taskgroup_id` or Search/Extract `session_id` is not a Task interaction ID.
 
 **IMPORTANT:** Always include `--no-wait` so the command returns immediately instead of blocking.
 
-Parse the `--json` output to extract `taskgroup_id` and `url`. The output is `{taskgroup_id, url, num_runs}` — there is no `interaction_id` field, do not look for one. Immediately tell the user:
+Save the `--json` output's `taskgroup_id`, `url` and `num_runs` immediately. There is no `interaction_id` field. If creation is interrupted or its response is lost, inspect whether the group was created before submitting another run. Immediately tell the user:
 
 - Enrichment has been kicked off
 - The monitoring URL where they can track progress
 
-Tell them they can background the polling step to continue working while it runs.
+The group runs server-side; polling can resume later using its saved ID.
 
 ## Step 2: Poll for results
 
-Pick a concrete output path (e.g., `/tmp/enrichment-acme.json`). Note: the file is JSON regardless of the extension you choose — it's an array of `{input, output}` objects, not a CSV. Name it `.json` to avoid confusing yourself or the user.
+Pick a persistent, run-specific output path (e.g., `enrichment-acme-tgrp-<id>.json`). Polling overwrites its output file, so inspect any existing file and use a new path unless replacement is intended. The output is JSON regardless of extension: an array of rows with `input` and either `output` or `error`. Async polling does not include basis or per-row interaction IDs; do not invent citations or context IDs.
 
 ```bash
-parallel-cli enrich poll "$TASKGROUP_ID" --timeout 540 --output "/tmp/enrichment-<descriptive-name>.json"
+parallel-cli enrich poll "$TASKGROUP_ID" --timeout 60 --output "enrichment-<descriptive-name>-<group-id>.json"
 ```
 
 Important:
 
-- Use `--timeout 540` (9 minutes) to stay within tool execution limits
-- The `--target` from step 1 is unused in `--no-wait` mode — only `--output` here determines where results are saved, and the file is always JSON
+- Keep polls bounded; `--timeout 60` allows progress updates between waits.
+- The `--target` from step 1 is unused in `--no-wait` mode. Only `--output` here determines where results are saved, and the file is always JSON.
+- A completed group can include failed rows. Count rows containing `output` separately from rows containing `error` and compare their total with `num_runs`; an empty or incomplete file is not successful enrichment of the entire input.
 
-### If the poll times out
+### If polling times out or is interrupted
 
-Enrichment of large datasets can take longer than 9 minutes. If the poll exits without completing:
+Timeout exit 5 or interruption ends the local wait. Check group state before saying it is still running:
 
-1. Tell the user the enrichment is still running server-side
-2. Re-run the same `parallel-cli enrich poll` command to continue waiting
+```bash
+parallel-cli enrich status "$TASKGROUP_ID" --json
+```
+
+Inspect `is_active`, `status_counts` and `num_runs`. Resume the same poll for an active group, or retrieve results for an inactive group and report failures or unresolved rows. Do not recreate the group on a timeout or automatically rerun failed rows. A local file-write failure can be retried with the same group ID and a writable output path.
+
+### If the user requested CSV
+
+Convert the saved JSON locally into a separate CSV. Preserve every original input column and row, including duplicate and failed rows; keep enrichment fields separate from conflicting input names and include an error column for failures. Do not assume streamed rows match original input order or guess a join when row identity is ambiguous. Validate the row count and leave the input CSV untouched. This is local conversion, not a CSV produced by async polling; report both JSON and CSV paths.
 
 ## Response format
 
 **After step 1:** Share the monitoring URL (for tracking progress).
 
 **After step 2:**
 
-1. Report number of rows enriched
-2. Preview first few rows from the output file (it's a JSON array of `{input, output}` objects)
+1. Report successful, failed and total row counts, with any missing results called out.
+2. Preview a few successful rows and a representative failure if present, without claiming all rows succeeded.
 3. Tell the user the full path to the output file
 
-Do NOT re-share the monitoring URL after completion — the results are in the output file.
+After completion, link the saved output rather than repeating the monitoring URL.
 
 ## Setup
 
@@ -102,4 +110,6 @@ If `parallel-cli` is not found, install and authenticate:
 /parallel:parallel-cli-setup
 ```
 
-If any `parallel-cli enrich` command returns `403`, tell the user balance is likely required. Offer to run `parallel-cli balance get`, and if needed ask for explicit confirmation before running `parallel-cli balance add <amount_cents>`. Then retry the original enrichment command.
+If a documented option or command is missing, identify the install method and upgrade through that method: standalone `parallel-cli update`; pipx `pipx upgrade parallel-web-tools`; uv `uv tool upgrade parallel-web-tools`; Homebrew `brew upgrade parallel-web/tap/parallel-cli`; npm `npm update -g parallel-web-cli`. Recheck version and help in the agent's terminal before retrying.
+
+For authentication or API errors, inspect the returned message. A `403` can indicate permissions, account policy or billing; it does not prove low balance. Check `parallel-cli auth --json` and its `authenticated` boolean when relevant without exposing credentials. Only a billing-specific error warrants a balance check, and adding funds needs explicit confirmation. Reuse saved group IDs; do not automatically retry an ambiguous creation.