docs: complete Cowork documentation v1.0 (Phase 2)

- Create comprehensive Cowork docs (23 files in cowork/)
  - 6 guides: overview, getting started, capabilities, security, troubleshooting
  - 60+ ready-to-use prompts across 4 categories
  - 5 step-by-step workflows
  - Reference materials: cheatsheet, FAQ, comparison, glossary

- Integrate Perplexity research (P0/P1/P2)
  - Exact error messages with solutions (VPN, Chrome host, context limits)
  - Competitive analysis (vs Copilot/Gemini/ChatGPT/Apple Intelligence)
  - Enterprise validation (TELUS, Rakuten, Zapier stats)
  - OCR accuracy benchmarks (97% field, 63% line-item)
  - Token budget planning per task type

- Document critical limitations
  - VPN incompatibility (#1 community issue)
  - Context limit reality (165K vs 200K theoretical)
  - Platform constraints (macOS only)
  - Usage limits and pricing (Pro $20, Max $100-200)

- Update central files
  - README.md: detailed Cowork section with tables
  - VERSION: 3.9.6 → 3.9.7
  - machine-readable/reference.yaml: add cowork_reference entry
  - machine-readable/cowork-reference.yaml: new LLM-optimized index (~1.5K tokens)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

machine-readable/cowork-reference.yaml

@@ -0,0 +1,220 @@
+# cowork-reference.yaml
+# Quick lookup for Claude Cowork - ~1.5K tokens target
+# Source: cowork/ documentation
+# Purpose: Condensed index for LLMs to quickly answer user questions about Cowork
+
+version: "1.0.0"
+updated: "2026-01-20"
+status: "research-preview"
+
+# ════════════════════════════════════════════════════════════════
+# CORE DOCUMENTATION - File paths for detailed info
+# ════════════════════════════════════════════════════════════════
+docs:
+  hub: "cowork/README.md"
+  overview: "cowork/guide/00-overview.md"
+  getting_started: "cowork/guide/01-getting-started.md"
+  capabilities: "cowork/guide/02-capabilities.md"
+  security: "cowork/guide/03-security.md"
+  troubleshooting: "cowork/guide/04-troubleshooting.md"
+  cheatsheet: "cowork/reference/cheatsheet.md"
+  faq: "cowork/reference/faq.md"
+  comparison: "cowork/reference/comparison.md"
+  glossary: "cowork/reference/glossary.md"
+
+# ════════════════════════════════════════════════════════════════
+# PROMPTS LIBRARY (60+ ready-to-use)
+# ════════════════════════════════════════════════════════════════
+prompts:
+  file_ops: "cowork/prompts/file-ops.md"  # 20 prompts
+  document_creation: "cowork/prompts/document-creation.md"  # 15 prompts
+  data_extraction: "cowork/prompts/data-extraction.md"  # 15 prompts
+  research: "cowork/prompts/research.md"  # 17 prompts
+
+# ════════════════════════════════════════════════════════════════
+# WORKFLOWS (step-by-step guides)
+# ════════════════════════════════════════════════════════════════
+workflows:
+  file_organization: "cowork/workflows/file-organization.md"
+  expense_tracking: "cowork/workflows/expense-tracking.md"
+  report_synthesis: "cowork/workflows/report-synthesis.md"
+  meeting_prep: "cowork/workflows/meeting-prep.md"
+  team_handoff: "cowork/workflows/team-handoff.md"
+
+# ════════════════════════════════════════════════════════════════
+# QUICK REFERENCE - Essential facts
+# ════════════════════════════════════════════════════════════════
+essentials:
+  what: "Agentic desktop feature for knowledge workers - file manipulation without code"
+  platform: "macOS only (Windows planned, Linux not announced)"
+  subscription: "Pro ($20/mo) or Max ($100-200/mo) - both have access"
+  usage_limits: "Resets every 5 hours; Pro ~1-1.5h intensive use, Max 5x-20x more"
+  context: "~200K tokens theoretical, ~165K effective (system overhead)"
+  vpn_compatible: "NO - #1 issue, VM routing conflict"
+
+# ════════════════════════════════════════════════════════════════
+# CAN DO / CANNOT DO
+# ════════════════════════════════════════════════════════════════
+capabilities:
+  can_do:
+    - "Read/write local files in sandbox"
+    - "Create Office docs (Word, Excel, PowerPoint)"
+    - "Extract data from images (OCR)"
+    - "Organize folders/files"
+    - "Web research via Chrome"
+    - "Generate PDFs"
+  cannot_do:
+    - "Execute code or scripts"
+    - "Make API calls"
+    - "Access cloud storage directly"
+    - "Process audio/video"
+    - "Work with VPN active"
+    - "Run on Windows/Linux"
+    - "Operate in background"
+
+# ════════════════════════════════════════════════════════════════
+# PROMPTING FORMULA (CTOC)
+# ════════════════════════════════════════════════════════════════
+prompting:
+  framework: "CTOC - Context → Task → Output → Constraints"
+  context: "Background, files, situation"
+  task: "Clear single objective"
+  output: "Exact format and location"
+  constraints: "Rules, limits, preferences"
+  example: |
+    CONTEXT: I have 50 receipts from Paris business trip in ~/Cowork-Workspace/input/receipts/
+    TASK: Extract all expenses into a spreadsheet
+    OUTPUT: Save as ~/Cowork-Workspace/output/paris-expenses.xlsx
+    CONSTRAINTS: Use EUR currency, semicolon formulas, categorize by type
+
+# ════════════════════════════════════════════════════════════════
+# COMMON ERRORS - Exact messages + solutions
+# ════════════════════════════════════════════════════════════════
+errors:
+  vm_timeout:
+    message: "Failed to start Claude's workspace — VM connection timeout after 60 seconds"
+    cause: "VPN active"
+    solution: "Disconnect VPN completely before using Cowork"
+  chrome_host:
+    message: "Chrome native messaging host not found"
+    cause: "Extension mismatch or missing host"
+    solution: "Manual installation via bash (see troubleshooting doc)"
+  context_limit:
+    message: "Context limit reached"
+    cause: "System overhead (~25-35K tokens)"
+    actual_limit: "~165K usable (not 200K)"
+    solution: "Break into batches of 10-20 files"
+  access_denied:
+    message: "Access denied — path outside allowed directories"
+    cause: "Folder not granted"
+    solution: "Re-grant folder access in System Preferences"
+  session_terminated:
+    message: "Session terminated unexpectedly"
+    cause: "Sleep/background/VPN"
+    solution: "Keep app foreground, disable sleep, disconnect VPN"
+
+# ════════════════════════════════════════════════════════════════
+# TOKEN BUDGET - Task costs
+# ════════════════════════════════════════════════════════════════
+tokens:
+  simple_qa: "5K-10K"
+  file_inventory: "20K-30K"
+  small_file_org: "30K-50K (10-20 files)"
+  large_file_org: "80K-150K (50+ files)"
+  multi_doc_synthesis: "50K-100K"
+  ocr_batch: "60K-100K (10+ images)"
+  agentic_overhead: "15-30% (Plan→Execute→Check cycles)"
+
+# ════════════════════════════════════════════════════════════════
+# OCR ACCURACY (from Perplexity research)
+# ════════════════════════════════════════════════════════════════
+ocr:
+  field_extraction: "~97% (vendor, date, totals)"
+  line_items: "~63% (table rows)"
+  warning: "Budget 30-50% of 'saved' time for error correction"
+  best_for: "Single-currency, clear fonts, standard formats"
+
+# ════════════════════════════════════════════════════════════════
+# COMPETITIVE POSITIONING
+# ════════════════════════════════════════════════════════════════
+competition:
+  unique_strength: "Only assistant with true multi-step autonomy + local files + browser automation"
+  vs_copilot: "Better autonomy, worse OCR accuracy"
+  vs_gemini: "Better autonomy, smaller context (165K vs 1M+)"
+  vs_chatgpt: "Better autonomy, macOS only vs cross-platform"
+  vs_apple_intelligence: "Better capabilities, cloud vs on-device"
+  best_ocr: "Microsoft Copilot"
+  best_context: "Gemini Advanced (1M+ tokens)"
+  best_privacy: "Apple Intelligence (on-device)"
+  best_autonomy: "Cowork"
+
+# ════════════════════════════════════════════════════════════════
+# ENTERPRISE VALIDATION (Claude general, not Cowork-specific)
+# ════════════════════════════════════════════════════════════════
+enterprise:
+  telus: "$90M value, 500K hours saved"
+  rakuten: "87.5% reduction in processing time"
+  zapier: "89% employee adoption"
+  note: "Stats for Claude in general - validates underlying AI capabilities"
+
+# ════════════════════════════════════════════════════════════════
+# LIMITATIONS & CONSTRAINTS
+# ════════════════════════════════════════════════════════════════
+limitations:
+  environment:
+    - "VPN incompatible (VM routing conflict)"
+    - "macOS only (Windows planned, Linux not announced)"
+    - "Requires app foreground (no background operation)"
+    - "No session persistence across restarts"
+  technical:
+    - "No code execution"
+    - "No API calls"
+    - "No cloud storage direct access"
+    - "No audio/video processing"
+    - "Context limit hits at 165K (not 200K)"
+  workflow:
+    - "Pro tier exhausts in ~1-1.5h intensive use"
+    - "Usage resets every 5 hours (not daily)"
+    - "No cross-session memory"
+    - "Connector reliability inconsistent"
+
+# ════════════════════════════════════════════════════════════════
+# DECISION FLOWCHART
+# ════════════════════════════════════════════════════════════════
+decide:
+  use_cowork_when:
+    - "Need to organize/rename files"
+    - "Create Office documents"
+    - "Extract data from images/receipts"
+    - "Compile research → documents"
+    - "Batch file operations"
+    - "Browser automation tasks"
+  use_alternative_when:
+    - "Need code execution → Claude Code"
+    - "Need best OCR → Microsoft Copilot"
+    - "Need 1M+ context → Gemini Advanced"
+    - "Privacy critical → Apple Intelligence"
+    - "On Windows/Linux → Copilot or ChatGPT"
+    - "VPN required → Claude Code"
+
+# ════════════════════════════════════════════════════════════════
+# QUICK START (5 steps)
+# ════════════════════════════════════════════════════════════════
+quick_start:
+  1: "Enable Cowork in Claude Desktop → Settings → Features"
+  2: "Create ~/Cowork-Workspace/{input,output}"
+  3: "Grant folder access when prompted"
+  4: "Use CTOC framework for prompts"
+  5: "Review plan before approval"
+
+# ════════════════════════════════════════════════════════════════
+# GOLDEN RULES
+# ════════════════════════════════════════════════════════════════
+rules:
+  1: "Always review plan before approval"
+  2: "Dedicated workspace only (never Documents/Desktop)"
+  3: "No credentials in workspace"
+  4: "Verify file sources (prompt injection risk)"
+  5: "Budget 30-50% time for OCR error correction"
+  6: "Disconnect VPN before using"
+  7: "Backup before destructive operations"

machine-readable/reference.yaml

@@ -3,8 +3,8 @@
 # Source: guide/ultimate-guide.md
 # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
 
-version: "3.9.6"
-updated: "2026-01"
+version: "3.9.7"
+updated: "2026-01-20"
 
 # ════════════════════════════════════════════════════════════════
 # DEEP DIVE - Line numbers in guide/ultimate-guide.md
@@ -119,7 +119,8 @@ deep_dive:
   ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:449"
   ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:959"
   voice_refine_skill: "examples/skills/voice-refine/SKILL.md"
-  # Cowork documentation (expanded - see cowork/)
+  # Cowork documentation (v1.0 - complete)
+  cowork_reference: "machine-readable/cowork-reference.yaml"  # Dedicated YAML index
   cowork_hub: "cowork/README.md"
   cowork_summary: "guide/cowork.md"
   cowork_overview: "cowork/guide/00-overview.md"