feat(mcp): auto-deploy CLAUDE.md to Cowork working folder on session start

Adds a SessionStart hook that copies a qsv workflow guidance CLAUDE.md
into the Cowork "Work in a folder" directory if one doesn't already exist.
Existing CLAUDE.md files are never overwritten.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jqnatividad

.claude/skills/.claude-plugin/plugin.json

@@ -21,5 +21,14 @@
     "sql",
     "data-quality"
   ],
-  "mcpServers": "./.mcp.json"
+  "mcpServers": "./.mcp.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/cowork-setup.sh"
+      }
+    ]
+  }
 }

.claude/skills/cowork-CLAUDE.md

@@ -0,0 +1,49 @@
+# qsv Data Wrangling - Workflow Guide
+
+This CLAUDE.md was auto-deployed by the qsv plugin to provide workflow guidance.
+You can edit or replace it — it will NOT be overwritten on future sessions.
+
+---
+
+## Workflow Order
+
+For new files:
+1. **`qsv_list_files`** to discover files in the working directory
+2. **`qsv_index`** for files >10MB (enables faster processing)
+3. **`qsv_stats --cardinality --stats-jsonl`** to create a stats cache
+4. Then run analysis/transformation commands
+
+The stats cache accelerates: `frequency`, `schema`, `tojsonl`, `sqlp`, `joinp`, `pivotp`, `describegpt`, `moarstats`, `sample`.
+
+SQL queries on CSV inputs auto-convert to Parquet before execution.
+
+## File Handling
+
+- Save outputs to files with descriptive names rather than returning large results to chat.
+- Ensure output files are saved to the qsv working directory.
+- **Parquet** is ONLY for `sqlp`/DuckDB; all other qsv commands require CSV/TSV/SSV input.
+- The working directory is automatically synced from the MCP client's root directory when available.
+- If the auto-synced directory is incorrect or no root is provided, call **`qsv_set_working_dir`** to set it manually.
+- In Claude Cowork, verify the working directory matches the "Work in a folder" path by calling **`qsv_get_working_dir`**, and correct it with **`qsv_set_working_dir`** if needed.
+
+## Tool Composition
+
+- **`qsv_sqlp`** auto-converts CSV inputs to Parquet, then routes to DuckDB when available for better SQL compatibility and performance; falls back to Polars SQL otherwise.
+- For multi-file SQL queries, convert all files to Parquet first with **`qsv_to_parquet`**, then use `read_parquet()` references in SQL.
+- For custom row-level logic, use **`qsv_command`** with `command="luau"`.
+
+## Memory Limits
+
+Commands `dedup`, `sort`, `reverse`, `table`, `transpose`, `pragmastat` load entire files into memory.
+
+For files >1GB, prefer `extdedup`/`extsort` alternatives via **`qsv_command`**.
+
+Check column cardinality with **`qsv_stats`** before running `frequency` or `pivotp` to avoid huge output.
+
+## Tool Discovery
+
+Use **`qsv_search_tools`** to discover commands beyond the initially loaded core tools. There are 56 qsv commands available covering selection, filtering, transformation, aggregation, joining, validation, formatting, conversion, and more.
+
+## Operation Timeout
+
+qsv operations can take significant time on larger files. The MCP server's default operation timeout is 10 minutes (configurable via `QSV_MCP_OPERATION_TIMEOUT_MS`, max 30 minutes). Allow operations to run to completion. Check the current timeout with **`qsv_config`**.

.claude/skills/scripts/cowork-setup.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# cowork-setup.sh — SessionStart hook
+# Copies a qsv CLAUDE.md template into the Cowork working folder
+# if one doesn't already exist.
+
+set -euo pipefail
+
+# Read hook input JSON from stdin
+INPUT=$(cat)
+
+# Extract cwd from the hook input
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+
+if [ -z "$CWD" ]; then
+  exit 0
+fi
+
+TEMPLATE="${CLAUDE_PLUGIN_ROOT}/cowork-CLAUDE.md"
+TARGET="${CWD}/CLAUDE.md"
+
+# Ensure the template exists
+if [ ! -f "$TEMPLATE" ]; then
+  exit 0
+fi
+
+if [ -f "$TARGET" ]; then
+  # Existing CLAUDE.md — don't overwrite
+  cat <<EOF
+{"additionalContext": "An existing CLAUDE.md was found at ${TARGET}. It was NOT overwritten. Inform the user their existing CLAUDE.md is being used."}
+EOF
+else
+  # Copy the template
+  cp "$TEMPLATE" "$TARGET"
+  cat <<EOF
+{"additionalContext": "A qsv CLAUDE.md was created at ${TARGET}. Inform the user that qsv workflow guidance has been set up in their working folder."}
+EOF
+fi