From 09eb141976e773374cdc83dcf80f857d08b76c7b Mon Sep 17 00:00:00 2001
From: Florian BRUNIAUX <florian@bruniaux.com>
Date: Tue, 20 Jan 2026 08:36:35 +0100
Subject: [PATCH] docs: v3.9.6 - Trust Calibration, Vibe Coding Trap,
 reference.yaml sync
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added:
- ultimate-guide.md: Trust Calibration section (1.7) with research-backed verification strategies
- ultimate-guide.md: Infrastructure as Code Skills (Anton Babenko's terraform-skill)
- learning-with-ai.md: "The Vibe Coding Trap" anti-pattern (Karpathy, Feb 2025)
- learning-with-ai.md: "Reality of AI Productivity" section with research
- learning-with-ai.md: External resource link to leerob.com/ai (AI fundamentals)
- IDEAS.md: "Vibe Coding Discourse" watching entry

Changed:
- reference.yaml: Complete line number synchronization (~55 entries)
  Guide grew from ~9900 to 11154 lines; all deep_dive references updated
- Version bump: 3.9.5 → 3.9.6

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CHANGELOG.md                    |  49 ++--
 IDEAS.md                        |   8 +
 README.md                       |  18 +-
 VERSION                         |   2 +-
 guide/README.md                 |  15 +-
 guide/ai-ecosystem.md           |   7 +-
 guide/cheatsheet.md             |   4 +-
 guide/cowork.md                 | 463 +++-----------------------------
 guide/learning-with-ai.md       |  14 +
 guide/ultimate-guide.md         |  54 +++-
 machine-readable/reference.yaml | 153 ++++++-----
 11 files changed, 268 insertions(+), 519 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ea72fc5..c62259c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,8 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [3.9.6] - 2026-01-20
+
 ### Added
 
+- **ultimate-guide.md: Section 5.5 "Infrastructure as Code Skills"** — New community skill repository (~50 lines)
+  - Anton Babenko's terraform-skill (creator of terraform-aws-modules, 1B+ downloads)
+  - Covers testing, module development, CI/CD, security, patterns
+  - Notable for marketplace distribution (.claude-plugin/), structured references, test coverage
+  - Source: [GitHub repo](https://github.com/antonbabenko/terraform-skill)
+
 - **ultimate-guide.md: Section 1.7 "Trust Calibration: When and How Much to Verify"** — New section (~155 lines)
   - Research-backed stats table (ACM, Veracode, CodeRabbit, Cortex.io sources)
   - Verification spectrum (boilerplate → security-critical)
@@ -15,29 +23,40 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - "Prove It Works" checklist (functional, security, integration, quality)
   - Anti-patterns table (6 common mistakes)
   - Attribution to Addy Osmani's "AI Code Review" (Jan 2026)
-- **ultimate-guide.md: New pitfall in Learning & Adoption section** — "Trust AI output without proportional verification"
-- **reference.yaml: trust_calibration deep_dive entry** — Line 1039
 
-### Changed
+- **ultimate-guide.md: New pitfall** — "Trust AI output without proportional verification"
 
-- **ultimate-guide.md: Section renumbering** — "Eight Beginner Mistakes" moved from 1.7 → 1.8
-- **reference.yaml: pitfalls line number** — Updated 7689 → 8050 (shifted by new content)
-
----
-
-- **learning-with-ai.md: "The Reality of AI Productivity" section** — New §3 (~55 lines)
+- **learning-with-ai.md: Section 3 "The Reality of AI Productivity"** — New section (~55 lines)
   - Productivity curve phases (Wow Effect → Targeted Gains → Sustainable Plateau)
   - High-gain vs low/negative-gain task categorization
   - Team success factors (guidelines, code review, mentorship)
-  - Cross-references to other sections for coherent narrative
+
+- **reference.yaml**: `trust_calibration` (line 1039), `community_skills_cybersec` (4786), `community_skills_iac` (4871), `vibe_coding_trap` (81)
+
+- **learning-with-ai.md: "The Vibe Coding Trap" section** — New anti-pattern documentation (~15 lines)
+  - Term coined by Andrej Karpathy (Feb 2025, Collins Word of the Year 2025)
+  - Symptoms checklist + Karpathy's caveat ("throwaway projects" vs production)
+  - Links to UVAL Protocol as antidote
+
+- **IDEAS.md: "Vibe Coding Discourse"** — New Watching entry
+  - Tracks "developer as architect" narrative evolution
+  - Source: Craig Adam "Agile is Out, Architecture is Back" (Medium)
+
+- **learning-with-ai.md: External Resources** — Added [leerob.com/ai](https://leerob.com/ai) link
+  - AI fundamentals for engineers (ML, neural networks, transformers, tokenization)
+  - Score 3/5 eval: complement utile, not deep integration
+  - Source: Lee Robinson (Nov 2024)
 
 ### Changed
 
-- **learning-with-ai.md: Three Patterns productivity trajectory table** — Shows productivity by pattern over time
-- **learning-with-ai.md: 70/30 Split research callout** — Links ratio to productivity research
-- **learning-with-ai.md: Case Study organizational link** — Connects to team success factors
-- **learning-with-ai.md: Sources section** — Added "Productivity Research" subsection with 5 sources (GitHub, McKinsey, Stack Overflow, Uplevel, DORA)
-- **learning-with-ai.md: ToC renumbered** — 14 sections (was 13)
+- **reference.yaml**: Complete line number synchronization (~55 entries updated)
+  - Guide grew from ~9900 to 11154 lines; all deep_dive references now accurate
+  - Added "Updated 2026-01-20" comment for tracking
+  - Major corrections: cost_optimization (8047→8833), interaction_loop (1063→1299), etc.
+
+- **ultimate-guide.md**: Section renumbering — "Eight Beginner Mistakes" moved 1.7 → 1.8
+- **learning-with-ai.md**: Three Patterns productivity trajectory table, 70/30 Split research callout, Sources section (+5 sources)
+- **learning-with-ai.md**: ToC renumbered (14 sections, was 13)
 
 ## [3.9.5] - 2026-01-19
 
diff --git a/IDEAS.md b/IDEAS.md
index 38bd8c7..30f9f83 100644
--- a/IDEAS.md
+++ b/IDEAS.md
@@ -102,6 +102,14 @@ Using external LLMs (Gemini, GPT-4) as "second opinion" from Claude Code.
 
 **Source:** [daily.dev article](https://app.daily.dev/posts/make-claude-code-opus-talk-to-gemini-pro-b7pyiq394)
 
+### Vibe Coding Discourse
+
+Evolution of the "developer as architect" narrative in AI-assisted development.
+
+**Reference:** [Craig Adam - "Agile is Out, Architecture is Back"](https://medium.com/@craig_32726/agile-is-out-architecture-is-back-7586910ab810)
+
+**Status:** Watching. Term "vibe coding" now mainstream (Collins Word of the Year 2025).
+
 ---
 
 ## Discarded Ideas
diff --git a/README.md b/README.md
index 6f2f8c7..909a162 100644
--- a/README.md
+++ b/README.md
@@ -276,6 +276,22 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv
 
 </details>
 
+<details>
+<summary><strong>Claude Cowork (for Non-Developers)</strong></summary>
+
+**Cowork** is Claude's agentic desktop feature for knowledge workers — same AI, files-only interface.
+
+| Resource | Description |
+|----------|-------------|
+| **[Cowork Documentation](./cowork/README.md)** | Complete guide hub |
+| [Getting Started](./cowork/guide/01-getting-started.md) | Setup and first workflow |
+| [Prompt Library](./cowork/prompts/) | 50+ ready-to-use prompts |
+| [Cheatsheet](./cowork/reference/cheatsheet.md) | 1-page reference |
+
+**Status**: Research preview (Pro or Max subscription, macOS only)
+
+</details>
+
 <details>
 <summary><strong>Ecosystem & Related Resources</strong></summary>
 
@@ -317,7 +333,7 @@ Licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
 
 ---
 
-*Version 3.9.5 | January 2026 | Crafted with Claude*
+*Version 3.9.6 | January 2026 | Crafted with Claude*
 
 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
diff --git a/VERSION b/VERSION
index 11aaa06..1635d0f 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-3.9.5
+3.9.6
diff --git a/guide/README.md b/guide/README.md
index 3aa9a71..48965d5 100644
--- a/guide/README.md
+++ b/guide/README.md
@@ -17,9 +17,22 @@ Core documentation for mastering Claude Code.
 | [methodologies.md](./methodologies.md) | 15 development methodologies reference (TDD, SDD, BDD, etc.) | 20 min |
 | [security-hardening.md](./security-hardening.md) | Security threats, MCP vetting, injection defense | 25 min |
 | [ai-ecosystem.md](./ai-ecosystem.md) | Complementary AI tools (Perplexity, Gemini, Kimi, NotebookLM) | 25 min |
-| [cowork.md](./cowork.md) | Claude Cowork: Agentic Desktop for Knowledge Workers | 15 min |
+| [cowork.md](./cowork.md) | Claude Cowork: Summary (see [cowork/](../cowork/) for full docs) | 5 min |
 | [workflows/](./workflows/) | Practical workflow guides for Claude Code | 30 min |
 
+### Cowork Documentation
+
+For knowledge workers using Claude Cowork (agentic desktop):
+
+| Resource | Description |
+|----------|-------------|
+| **[Cowork Hub](../cowork/README.md)** | Complete Cowork documentation |
+| [Getting Started](../cowork/guide/01-getting-started.md) | Setup and first workflow |
+| [Capabilities](../cowork/guide/02-capabilities.md) | What Cowork can/cannot do |
+| [Security Guide](../cowork/guide/03-security.md) | Safe usage practices |
+| [Prompt Library](../cowork/prompts/) | 50+ ready-to-use prompts |
+| [Cheatsheet](../cowork/reference/cheatsheet.md) | 1-page quick reference |
+
 ### Workflows
 
 Hands-on guides for effective development patterns:
diff --git a/guide/ai-ecosystem.md b/guide/ai-ecosystem.md
index 3850869..e1fd300 100644
--- a/guide/ai-ecosystem.md
+++ b/guide/ai-ecosystem.md
@@ -718,7 +718,7 @@ Cowork extends Claude's agentic capabilities to non-technical users via the Clau
 | **Maturity** | Production | **Preview** | Production |
 | **Connectors** | MCP servers | **Local only** | Integrations |
 | **Platform** | All | macOS only | All |
-| **Subscription** | Usage-based | Max only (~$200/mo) | All tiers |
+| **Subscription** | Usage-based | Pro or Max | All tiers |
 
 ### When to Use What
 
@@ -779,9 +779,8 @@ Shared context via `~/Shared/CLAUDE.md` file.
 
 | Aspect | Status |
 |--------|--------|
-| Subscription | Max only (~$200/month) |
-| Platform | macOS only (Windows/Linux announced) |
-| Waitlist | Available for Pro/Team plans |
+| Subscription | Pro ($20/mo) or Max ($100-200/mo) |
+| Platform | macOS only (Windows planned, Linux not announced) |
 | Stability | Research preview |
 
 > **Deep Dive**: For complete security practices, troubleshooting, and detailed use cases, see [guide/cowork.md](./cowork.md).
diff --git a/guide/cheatsheet.md b/guide/cheatsheet.md
index 3135f5e..a8b12be 100644
--- a/guide/cheatsheet.md
+++ b/guide/cheatsheet.md
@@ -6,7 +6,7 @@
 
 **Written with**: Claude (Anthropic)
 
-**Version**: 3.9.5 | **Last Updated**: January 2026
+**Version**: 3.9.6 | **Last Updated**: January 2026
 
 ---
 
@@ -411,4 +411,4 @@ where.exe claude; claude doctor; claude mcp list
 
 **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
 
-*Last updated: January 2026 | Version 3.9.5*
+*Last updated: January 2026 | Version 3.9.6*
diff --git a/guide/cowork.md b/guide/cowork.md
index 1378a6c..937f300 100644
--- a/guide/cowork.md
+++ b/guide/cowork.md
@@ -1,461 +1,72 @@
 # Claude Cowork: Agentic Desktop for Knowledge Work
 
-> **Reading time**: ~15 minutes
->
-> **Purpose**: Understand Cowork's capabilities, limitations, and how it complements Claude Code for team workflows.
+> **Note**: This page is a summary. For comprehensive documentation, see the **[Complete Cowork Documentation](../cowork/README.md)**.
 
 ---
 
-> **Research Preview** (January 2026) — Limited documentation available.
-> Expect bugs, no production use recommended yet.
+## Quick Overview
 
----
+**Cowork** is Claude's agentic desktop feature that extends autonomous AI capabilities to non-technical users through the Claude Desktop app. Instead of terminal commands, Cowork accesses local folders and files directly.
 
-## Table of Contents
-
-- [1. Overview](#1-overview)
-- [2. Who Should Use Cowork?](#2-who-should-use-cowork)
-- [3. Architecture](#3-architecture)
-- [4. Claude Code vs Cowork vs Projects](#4-claude-code-vs-cowork-vs-projects)
-- [5. Use Cases](#5-use-cases)
-- [6. Security: Handle With Care](#6-security-handle-with-care)
-- [7. Known Issues & Troubleshooting](#7-known-issues--troubleshooting)
-- [8. Developer ↔ Non-Developer Workflows](#8-developer--non-developer-workflows)
-- [9. Availability & Roadmap](#9-availability--roadmap)
-- [Sources](#sources)
-
----
-
-## 1. Overview
-
-**Cowork** is Claude's agentic desktop feature that extends Claude's autonomous capabilities to non-technical users through the Claude Desktop app. Instead of terminal commands, Cowork accesses local folders and files directly.
-
-### What is Cowork?
-
-- **Research preview** released January 2026 for Max subscribers (macOS only)
-- Extends Claude Code's agentic architecture to knowledge workers
-- ~90% of Cowork was written by Claude itself ([Anthropic blog])
-- Focuses on file manipulation, organization, and document generation
-
-### Relationship to Claude Code
-
-Cowork shares the same backend architecture as Claude Code:
-- Same model capabilities (extended thinking, agentic loops)
-- Same limitations (no internet access without explicit tools)
-- Different interface: Desktop app vs Terminal
-
-**Key difference**: Cowork cannot execute arbitrary code—it manipulates files only.
-
----
-
-## 2. Who Should Use Cowork?
-
-### Good Fit
-
-| Persona | Use Case | Why Cowork |
-|---------|----------|------------|
-| **Project Manager** | File organization + status reports | Multi-step automation without coding |
-| **Data Analyst** | Local CSV/Excel → formatted reports | Native Excel formulas output |
-| **Writer/Editor** | Research notes → structured documents | Synthesis across many sources |
-| **Operations** | Receipt screenshots → expense reports | Multi-format input processing |
-
-### Poor Fit (For Now)
-
-| Persona | Limitation | Alternative |
-|---------|------------|-------------|
-| **Security-conscious enterprises** | No audit trail, no access controls | Wait for enterprise features |
-| **Heavy cloud users** | No Google Drive/Dropbox confirmed | Use native apps |
-| **Anyone needing reliability** | Preview = bugs, unexpected behavior | Wait for stable release |
-| **Code execution needs** | Files only, no scripts | Use Claude Code |
-
----
-
-## 3. Architecture
-
-### Local-First Design
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    CLAUDE DESKTOP APP                        │
-│  ┌─────────────────────────────────────────────────────────┐│
-│  │                     COWORK                               ││
-│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ ││
-│  │  │ Sub-Agent 1 │  │ Sub-Agent 2 │  │ Sub-Agent 3     │ ││
-│  │  │ (Analysis)  │  │ (Transform) │  │ (Organize)      │ ││
-│  │  └──────┬──────┘  └──────┬──────┘  └───────┬─────────┘ ││
-│  │         └────────────────┴─────────────────┘            ││
-│  │                          ↓                               ││
-│  │  ┌─────────────────────────────────────────────────────┐││
-│  │  │              LOCAL FOLDER SANDBOX                    │││
-│  │  │  ~/Cowork-Workspace/                                 │││
-│  │  │    ├── input/  (your files)                         │││
-│  │  │    └── output/ (generated files)                    │││
-│  │  └─────────────────────────────────────────────────────┘││
-│  └─────────────────────────────────────────────────────────┘│
-│                                                              │
-│  ┌─────────────────┐                                        │
-│  │ CHROME INTEGRATION │ ← Web tasks (with explicit action)  │
-│  └─────────────────┘                                        │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Key Technical Details
+### Key Facts
 
 | Aspect | Details |
 |--------|---------|
-| **Access model** | Local folder sandbox (user grants permission) |
-| **Cloud connectors** | Not confirmed (no Drive, Dropbox, etc. yet) |
-| **Sub-agents** | Parallel execution with fresh context per agent |
-| **Code execution** | **None** - Files only (no scripts, no commands) |
-| **Browser** | Chrome integration for web research tasks |
-| **Context limit** | ~200K tokens (~150-500 pages per session) |
-| **Output formats** | Excel (.xlsx with formulas), PowerPoint, Word, PDF, text |
-
-### What Cowork Cannot Do
-
-- Execute shell commands or scripts
-- Access cloud storage directly (as of Jan 2026)
-- Run code in any language
-- Access network resources without Chrome
-- Persist memory across sessions (except via files)
+| **Status** | Research preview (January 2026) |
+| **Access** | Pro ($20/mo) or Max ($100-200/mo) subscription, macOS only |
+| **Focus** | File manipulation, document generation, organization |
+| **Difference from Code** | No code execution—files only |
 
 ---
 
-## 4. Claude Code vs Cowork vs Projects
+## Quick Comparison
 
 | Aspect | Claude Code | Cowork | Projects |
 |--------|-------------|--------|----------|
-| **Target user** | Developers | Knowledge workers | Everyone |
-| **Interface** | Terminal/CLI | Desktop app | Chat interface |
-| **Access** | Shell + arbitrary code | Folder sandbox only | Documents only |
-| **Execute code** | Yes (full shell) | No | No |
-| **Outputs** | Code, scripts, any file | Excel, PPT, docs | Conversations |
-| **Maturity** | Production-ready | **Research preview** | Production-ready |
-| **Security docs** | Extensive | None yet | Standard |
-| **Context** | ~200K tokens | ~200K tokens | Project-scoped |
-| **Memory** | CLAUDE.md files | Via files | Project knowledge |
-| **Subscription** | Usage-based | Max only (~$200/mo) | All tiers |
-| **Platform** | macOS, Linux, Windows | macOS only | All |
+| **User** | Developers | Knowledge workers | Everyone |
+| **Interface** | Terminal | Desktop app | Web chat |
+| **Execute code** | Yes | No | No |
+| **File access** | Full | Folder sandbox | Upload only |
+| **Maturity** | Production | Research preview | Production |
 
-### Decision Flow
-
-```
-Need to execute code or scripts?
-├─ Yes → Claude Code
-└─ No → Need file manipulation?
-         ├─ Yes (local files) → Cowork
-         ├─ Yes (cloud files) → Wait or use native apps
-         └─ No (just conversation) → Projects
-```
+→ [Full Comparison](../cowork/reference/comparison.md)
 
 ---
 
-## 5. Use Cases
+## Use Cases
 
-### 5.1 File Organization
+- **File Organization** — Messy folders → organized structure
+- **Expense Tracking** — Receipts → Excel reports
+- **Report Synthesis** — Multiple docs → unified report
+- **Meeting Prep** — Research → briefing documents
 
-**Scenario**: Messy Downloads folder with 500+ files
-
-```
-INPUT:  ~/Downloads/ (mixed PDFs, images, zips, docs)
-PROMPT: "Organize my Downloads folder. Create folders by type
-        and date. Move files, don't copy. Show me the summary."
-OUTPUT: Organized structure + summary.txt
-```
-
-**Source**: [YouTube demo - File Organization]
-
-### 5.2 Expense Tracking
-
-**Scenario**: Receipt screenshots → Excel report
-
-```
-INPUT:  ~/Receipts/ (20 JPG/PNG receipt photos)
-PROMPT: "Extract expenses from these receipts.
-        Create an Excel file with Date, Vendor, Amount, Category.
-        Add a summary sheet with totals by category."
-OUTPUT: expenses.xlsx with formulas + summary sheet
-```
-
-**Source**: [LinkedIn post - Expense tracking demo]
-
-### 5.3 Report Synthesis
-
-**Scenario**: Scattered notes → structured document
-
-```
-INPUT:  ~/Notes/ (15 markdown files, 3 PDFs)
-PROMPT: "Create a project status report from these notes.
-        Structure: Executive Summary, Progress by Area, Risks,
-        Next Steps. Format as Word doc."
-OUTPUT: status-report.docx
-```
-
-**Source**: [Anthropic blog]
-
-### 5.4 Travel Planning
-
-**Scenario**: Multi-source research → itinerary
-
-```
-INPUT:  ~/Trip/ (saved webpages, flight confirmations, Airbnb PDFs)
-PROMPT: "Create a day-by-day itinerary for my Tokyo trip.
-        Include all confirmations, local recommendations,
-        and a packing checklist."
-OUTPUT: tokyo-itinerary.docx + checklist.xlsx
-```
-
-**Source**: [YouTube tutorial - Travel planning with Cowork]
-
-### 5.5 Meeting Preparation
-
-**Scenario**: Multiple docs → briefing document
-
-```
-INPUT:  ~/Meeting/ (company report PDF, LinkedIn profiles, news articles)
-PROMPT: "Create a briefing doc for my meeting with Acme Corp.
-        Include: company overview, key people, recent news,
-        talking points, questions to ask."
-OUTPUT: acme-briefing.docx
-```
+→ [Detailed Workflows](../cowork/workflows/)
 
 ---
 
-## 6. Security: Handle With Care
+## Security Summary
 
-> **No official security documentation exists for Cowork yet.**
-> The following is community-derived best practice.
+No official security documentation exists yet. Essential practices:
 
-### Risk Matrix
+1. **Dedicated workspace** — Never grant access to Documents/Desktop
+2. **Review plans** — Check every action before approval
+3. **No credentials** — Keep sensitive data out of workspace
+4. **Backup first** — Before destructive operations
 
-| Risk | Severity | Description | Mitigation |
-|------|----------|-------------|------------|
-| **Prompt injection via files** | HIGH | Malicious files with embedded instructions | Use dedicated folder, no untrusted content |
-| **Browser action abuse** | HIGH | Cowork taking unintended web actions | Review each web action before approval |
-| **Local file exposure** | MEDIUM | Accidental access to sensitive folders | Minimal permission scope |
-| **Data exfiltration** | MEDIUM | Sensitive data leaving local system | No credentials in workspace |
-| **Incomplete operations** | LOW | Half-finished file operations | Backup before destructive ops |
-
-### Security Best Practices
-
-1. **Create a dedicated Cowork folder**
-   ```
-   ~/Cowork-Workspace/
-   ├── input/    # Files you want processed
-   └── output/   # Generated files
-   ```
-   Never grant access to Documents, Desktop, or home folder directly.
-
-2. **Review task plans before execution**
-   - Cowork shows its plan before acting
-   - Read each step, especially file deletions or moves
-   - Reject and refine if scope seems wrong
-
-3. **Avoid instruction-like content in files**
-   - Don't process files containing "ignore previous instructions..."
-   - Be cautious with files from unknown sources
-   - Especially PDFs and documents with embedded text
-
-4. **No sensitive data in workspace**
-   - No API keys, passwords, tokens
-   - No personal financial documents
-   - No confidential work documents
-   - No credentials in any format
-
-5. **Backup before destructive operations**
-   - Before "organize my folder" → backup first
-   - Before "rename all files" → backup first
-   - Use Time Machine or manual copy
-
-6. **Browser permission caution**
-   - Grant Chrome access only when needed
-   - Review each web action Cowork proposes
-   - Revoke access after task completion
-
-### What NOT to Do
-
-```
-DANGEROUS: "You have access to my Documents folder"
-DANGEROUS: "Process all files in ~/"
-DANGEROUS: "Here's my password file, extract credentials"
-DANGEROUS: "Process this PDF from an unknown sender"
-RISKY:     "Delete all duplicates" (without backup)
-RISKY:     "Reorganize everything" (scope too broad)
-```
+→ [Complete Security Guide](../cowork/guide/03-security.md)
 
 ---
 
-## 7. Known Issues & Troubleshooting
+## Documentation
 
-> Based on community reports (January 2026)
-
-### Common Issues
-
-| Issue | Description | Workaround |
-|-------|-------------|------------|
-| **Incomplete tasks** | Cowork stops mid-operation | Break into smaller, explicit steps |
-| **Node.js download prompts** | Unexpected download dialogs | Accept or cancel, report to Anthropic |
-| **Session timeouts** | Long tasks getting interrupted | Keep app active, smaller batches |
-| **Browser actions failing** | Chrome integration not working | Grant explicit permissions in System Preferences |
-| **Excel formula errors** | Generated formulas don't work | Verify regional settings (comma vs semicolon) |
-| **File permission errors** | "Cannot access folder" | Re-grant permissions in Desktop app settings |
-
-### Reporting Issues
-
-Since this is a research preview, feedback is valuable:
-- **General support**: support.anthropic.com
-- **Feature requests**: Through the Claude Desktop app feedback
-- **Community discussion**: Reddit r/ClaudeAI
-
-### Recovery Procedures
-
-**If Cowork stops mid-task:**
-```
-1. Check ~/Cowork-Workspace/output/ for partial results
-2. Review what was completed vs planned
-3. Restart with explicit next step
-4. "Continue from where you stopped: [describe state]"
-```
-
-**If files are in unexpected state:**
-```
-1. Don't let Cowork "fix" without understanding
-2. Review manually what changed
-3. Restore from backup if needed
-4. Restart with clearer instructions
-```
-
----
-
-## 8. Developer ↔ Non-Developer Workflows
-
-One of Cowork's strengths is enabling collaboration between technical and non-technical team members.
-
-### Pattern 1: Dev Specs → PM Review
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ DEVELOPER (Claude Code)                                      │
-│                                                              │
-│ > "Generate a technical spec for the new auth system.       │
-│    Output as markdown in ~/Shared/specs/"                   │
-│                                                              │
-│ Output: ~/Shared/specs/auth-spec.md                         │
-└──────────────────────────────┬──────────────────────────────┘
-                               ↓
-┌─────────────────────────────────────────────────────────────┐
-│ PROJECT MANAGER (Cowork)                                     │
-│                                                              │
-│ > "Review the auth spec in ~/Shared/specs/.                 │
-│    Create a stakeholder summary with timeline estimates     │
-│    and risk assessment. Output as Word doc."                │
-│                                                              │
-│ Output: ~/Shared/docs/auth-summary.docx                     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Pattern 2: Research → Implementation
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ ANALYST (Cowork)                                             │
-│                                                              │
-│ > "Research competitors' pricing pages. Save screenshots     │
-│    and create a comparison matrix in Excel."                │
-│                                                              │
-│ Output: ~/Shared/research/pricing-comparison.xlsx            │
-└──────────────────────────────┬──────────────────────────────┘
-                               ↓
-┌─────────────────────────────────────────────────────────────┐
-│ DEVELOPER (Claude Code)                                      │
-│                                                              │
-│ > "Implement a pricing page based on the competitive        │
-│    analysis in ~/Shared/research/. Use our design system."  │
-│                                                              │
-│ Output: src/pages/pricing.tsx (+ tests)                     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Pattern 3: Shared Context via CLAUDE.md
-
-For teams using both tools, create a shared context file:
-
-```markdown
-# ~/Shared/CLAUDE.md
-
-## Project: Acme Platform v2
-
-### Conventions
-- All specs in ~/Shared/specs/
-- All docs in ~/Shared/docs/
-- All research in ~/Shared/research/
-
-### Current Sprint
-- Auth system redesign
-- Pricing page implementation
-- Q1 stakeholder report
-
-### Key Decisions
-- Using Clerk for auth (see specs/auth-decision.md)
-- Tailwind for styling
-- Q1 deadline: March 15
-```
-
-Both Claude Code and Cowork can reference this file for context.
-
----
-
-## 9. Availability & Roadmap
-
-### Current Status (January 2026)
-
-| Aspect | Status |
-|--------|--------|
-| **Subscription** | Max only (~$200/month) |
-| **Platform** | macOS only |
-| **Waitlist** | Available for Pro/Team plans |
-| **Stability** | Research preview (expect bugs) |
-
-### Expected Future
-
-| Feature | Status | Notes |
-|---------|--------|-------|
-| Windows support | Announced | No date |
-| Linux support | Announced | No date |
-| Cloud connectors | Unknown | Not confirmed |
-| Pro plan access | Waitlisted | Expected 2026 |
-| Enterprise features | Unknown | Audit trail, SSO, etc. |
-
-### How to Get Access
-
-1. **Max subscribers**: Enable in Claude Desktop app settings
-2. **Pro/Team subscribers**: Join waitlist at claude.ai/cowork
-3. **Enterprise**: Contact Anthropic sales
-
----
-
-## Sources
-
-All information in this document is derived from:
-
-| Source | Type | Link |
-|--------|------|------|
-| **Anthropic Blog** | Official | [claude.com/blog/cowork-research-preview](https://claude.com/blog/cowork-research-preview) |
-| **YouTube Demo - File Org** | Community | Search "Claude Cowork file organization" |
-| **LinkedIn Demos** | Community | Various posts tagged #ClaudeCowork |
-| **Reddit r/ClaudeAI** | Community | Cowork megathread |
-
-### Documentation Gaps
-
-As of January 2026, the following official documentation is **missing**:
-- Security guidelines
-- Best practices guide
-- API/automation documentation
-- Known issues list
-- Release notes / changelog
-- Enterprise deployment guide
-
-This guide will be updated as official documentation becomes available.
+| Resource | Description |
+|----------|-------------|
+| **[Complete Documentation](../cowork/README.md)** | Full Cowork guide hub |
+| **[Getting Started](../cowork/guide/01-getting-started.md)** | Setup and first workflow |
+| **[Capabilities](../cowork/guide/02-capabilities.md)** | What Cowork can/cannot do |
+| **[Prompt Library](../cowork/prompts/)** | 50+ ready-to-use prompts |
+| **[Cheatsheet](../cowork/reference/cheatsheet.md)** | 1-page quick reference |
+| **[FAQ](../cowork/reference/faq.md)** | Common questions |
 
 ---
 
diff --git a/guide/learning-with-ai.md b/guide/learning-with-ai.md
index 850af35..2bf0253 100644
--- a/guide/learning-with-ai.md
+++ b/guide/learning-with-ai.md
@@ -78,6 +78,19 @@ AI-assisted (right): Problem → Attempt → AI guidance → Understanding → S
 
 The struggle isn't optional. It's where learning happens.
 
+### The "Vibe Coding" Trap
+
+Term coined by [Andrej Karpathy](https://x.com/karpathy/status/1886192184808149383) (Feb 2025, Collins Word of the Year 2025): coding by "fully giving in to the vibes" without understanding the generated code.
+
+**Symptoms:**
+- Accept All without reading diffs
+- Copy-paste errors without understanding root cause
+- Debug by asking AI for random changes until it works
+
+**Karpathy's caveat:** "Not too bad for throwaway weekend projects" — but dangerous for production code you'll need to maintain.
+
+**Antidote:** The UVAL Protocol (§5) forces understanding before acceptance.
+
 ---
 
 ## The Reality of AI Productivity
@@ -928,6 +941,7 @@ See [methodologies.md](./methodologies.md) for:
 
 - [Anthropic Prompt Engineering Guide](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) — Better prompts = better learning
 - [The Pragmatic Programmer](https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/) — Timeless principles for deliberate practice
+- [AI for Engineers](https://leerob.com/ai) — AI fundamentals (ML, transformers, tokenization)
 
 ---
 
diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md
index 2c2f869..c4b9dfd 100644
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@@ -10,7 +10,7 @@
 
 **Last updated**: January 2026
 
-**Version**: 3.9.5
+**Version**: 3.9.6
 
 ---
 
@@ -4868,6 +4868,54 @@ skills: ["sql-injection-testing"]
 
 The skills appear to follow proper ethical hacking guidelines and include appropriate legal prerequisites, but as with any security tooling, verification is essential.
 
+### Infrastructure as Code Skills
+
+**Repository**: [antonbabenko/terraform-skill](https://github.com/antonbabenko/terraform-skill)
+**Author**: Anton Babenko (creator of [terraform-aws-modules](https://github.com/terraform-aws-modules), 1B+ downloads, AWS Community Hero)
+**Documentation**: [terraform-best-practices.com](https://www.terraform-best-practices.com/)
+
+A production-grade Claude Code skill for **Terraform** and **OpenTofu** infrastructure management, covering:
+
+**Testing & Validation**
+- Test strategy decision frameworks (native tests vs Terratest)
+- Workflow examples for different testing scenarios
+
+**Module Development**
+- Naming conventions and versioning patterns
+- Structural best practices for reusable modules
+
+**CI/CD Integration**
+- GitHub Actions and GitLab CI templates
+- Cost estimation and compliance checks baked in
+
+**Security & Compliance**
+- Static analysis and policy-as-code integration
+- Security scanning workflows
+
+**Patterns & Anti-patterns**
+- Side-by-side examples of recommended vs problematic approaches
+- Decision frameworks over prescriptive rules
+
+#### Why This Skill is Notable
+
+This skill demonstrates several best practices for production-grade skill development:
+
+1. **Marketplace distribution**: Uses `.claude-plugin/marketplace.json` for easy installation
+2. **Structured references**: Organized `references/` directory with knowledge base
+3. **Test coverage**: Includes `tests/` directory for skill validation
+4. **Decision frameworks**: Emphasizes frameworks over rigid rules, enabling contextual decisions
+
+#### Installation
+
+```bash
+# Via marketplace (if available)
+/install terraform-skill@antonbabenko
+
+# Manual installation
+cd ~/.claude/skills/
+git clone https://github.com/antonbabenko/terraform-skill.git terraform
+```
+
 #### Contributing
 
 If you create specialized skills for other domains (DevOps, data science, ML/AI, etc.), consider sharing them with the community through similar repositories or pull requests to existing collections.
@@ -10688,7 +10736,7 @@ If you work with non-technical team members, **Cowork** brings Claude's agentic
 
 **Collaboration pattern**: Developers use Claude Code for specs → PMs use Cowork for stakeholder summaries. Shared context via `~/Shared/CLAUDE.md`.
 
-> **Availability**: Max subscribers only (~$200/mo), macOS only (Jan 2026).
+> **Availability**: Pro ($20/mo) or Max ($100-200/mo) subscribers, macOS only (Jan 2026).
 > See [AI Ecosystem Section 9](./ai-ecosystem.md#9-claude-cowork-research-preview) for details.
 
 ## Further Reading
@@ -11103,4 +11151,4 @@ Thumbs.db
 
 **Contributions**: Issues and PRs welcome.
 
-**Last updated**: January 2026 | **Version**: 3.9.5
+**Last updated**: January 2026 | **Version**: 3.9.6
diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml
index bc48e0a..1be5cea 100644
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@@ -3,7 +3,7 @@
 # Source: guide/ultimate-guide.md
 # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
 
-version: "3.9.5"
+version: "3.9.6"
 updated: "2026-01"
 
 # ════════════════════════════════════════════════════════════════
@@ -44,6 +44,8 @@ deep_dive:
   learn_teach_command: "examples/commands/learn/teach.md"
   learn_alternatives_command: "examples/commands/learn/alternatives.md"
   learning_capture_hook: "examples/hooks/bash/learning-capture.sh"
+  # Anti-patterns
+  vibe_coding_trap: "guide/learning-with-ai.md:81"
   # Architecture internals (guide/architecture.md)
   architecture_master_loop: "guide/architecture.md:60"
   architecture_tools: "guide/architecture.md:130"
@@ -52,75 +54,84 @@ deep_dive:
   architecture_permissions: "guide/architecture.md:350"
   architecture_mcp: "guide/architecture.md:450"
   architecture_philosophy: "guide/architecture.md:580"
-  # Main guide (guide/ultimate-guide.md)
-  installation: 187
-  first_workflow: 268
-  essential_commands: 317
+  # Main guide (guide/ultimate-guide.md) - Updated 2026-01-20
+  installation: 196
+  first_workflow: 277
+  essential_commands: 326
   trust_calibration: 1039
-  working_with_images: 413
-  wireframing_tools: 483
-  figma_mcp: 520
-  image_optimization: 585
-  permission_modes: 751
-  interaction_loop: 1063
-  context_management: 1099
-  context_triage: 1212
-  session_vs_memory: 1245
-  fresh_context_pattern: 1289
-  plan_mode: 1822
-  rewind: 2000
-  mental_model: 2154
-  xml_prompting: 2211
-  semantic_anchors: 2664
+  working_with_images: 422
+  wireframing_tools: 492
+  figma_mcp: 529
+  image_optimization: 594
+  permission_modes: 760
+  interaction_loop: 1299
+  context_management: 1335
+  context_triage: 1448
+  session_vs_memory: 1481
+  fresh_context_pattern: 1525
+  subscription_limits: 1914
+  plan_mode: 2100
+  rewind: 2278
+  mental_model: 2360
+  xml_prompting: 2419
+  semantic_anchors: 2872
   semantic_anchors_catalog: "examples/semantic-anchors/anchor-catalog.md"
-  memory_files: 2952
-  claude_folder: 3103
-  settings: 3154
-  precedence_rules: 3376
-  agents: 3474
-  agent_template: 3547
-  agent_examples: 3685
-  skills: 4063
-  skill_template: 4183
-  skill_examples: 4251
-  commands: 4530
-  command_template: 4600
-  hooks: 4853
-  hook_templates: 4998
-  security_hooks: 5260
-  mcp_servers: 5401
-  mcp_config: 5695
-  mcp_security: 6063
-  cicd: 6381
-  ide_integration: 7070
-  feedback_loops: 7140
-  batch_operations: 7570
-  pitfalls: 8050
-  git_best_practices: 8190
-  subscription_limits: 1750
-  cost_optimization: 8047
-  session_teleportation: 9223
-  commands_table: 9399
-  shortcuts_table: 9432
-  troubleshooting: 9558
-  cheatsheet: 9933
-  daily_workflow: 10009
-  # AI Ecosystem (Section 11, ~line 10271)
-  ai_ecosystem: 10271
-  ai_ecosystem_complementarity: 10285
-  ai_ecosystem_tool_matrix: 10311
-  ai_ecosystem_workflows: 10336
-  ai_ecosystem_integration: 10462
+  memory_files: 3160
+  claude_folder: 3413
+  settings: 3464
+  precedence_rules: 3686
+  agents: 3827
+  agent_template: 3900
+  agent_examples: 4038
+  skills: 4420
+  skill_template: 4540
+  skill_examples: 4608
+  community_skills_cybersec: 4788
+  community_skills_iac: 4871
+  commands: 4939
+  command_template: 5009
+  hooks: 5262
+  hook_templates: 5407
+  security_hooks: 5669
+  mcp_servers: 5810
+  mcp_config: 6104
+  mcp_security: 6472
+  cicd: 6790
+  ide_integration: 7479
+  feedback_loops: 7549
+  batch_operations: 7979
+  pitfalls: 8098
+  git_best_practices: 8367
+  cost_optimization: 8833
+  session_teleportation: 9432
+  commands_table: 9608
+  shortcuts_table: 9641
+  troubleshooting: 9767
+  cheatsheet: 10142
+  daily_workflow: 10218
+  # AI Ecosystem (Section 11, ~line 10494)
+  ai_ecosystem: 10494
+  ai_ecosystem_complementarity: 10494
+  ai_ecosystem_tool_matrix: 10520
+  ai_ecosystem_workflows: 10545
+  ai_ecosystem_integration: 10671
   ai_ecosystem_detailed: "guide/ai-ecosystem.md"
   ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:902"
-  # Cowork documentation
-  cowork_full: "guide/cowork.md"
+  # Cowork documentation (expanded - see cowork/)
+  cowork_hub: "cowork/README.md"
+  cowork_summary: "guide/cowork.md"
+  cowork_overview: "cowork/guide/00-overview.md"
+  cowork_getting_started: "cowork/guide/01-getting-started.md"
+  cowork_capabilities: "cowork/guide/02-capabilities.md"
+  cowork_security: "cowork/guide/03-security.md"
+  cowork_troubleshooting: "cowork/guide/04-troubleshooting.md"
+  cowork_cheatsheet: "cowork/reference/cheatsheet.md"
+  cowork_comparison: "cowork/reference/comparison.md"
+  cowork_faq: "cowork/reference/faq.md"
+  cowork_prompts: "cowork/prompts/README.md"
+  cowork_workflows: "cowork/workflows/README.md"
   cowork_section: "guide/ai-ecosystem.md:701"
-  cowork_comparison: "guide/cowork.md:115"
-  cowork_use_cases: "guide/cowork.md:140"
-  cowork_security: "guide/cowork.md:200"
-  cowork_workflows: "guide/cowork.md:270"
-  cowork_ultimate_guide: 10521
+  cowork_ultimate_guide: 10725
 
 # ════════════════════════════════════════════════════════════════
 # DECISION TREE (most important - en premier)
@@ -385,7 +396,17 @@ ecosystem:
     description: "Claude Code for non-developers (desktop app)"
     status: "Research preview - Max/macOS only (Jan 2026)"
     blog: "https://claude.com/blog/cowork-research-preview"
-    guide: "guide/cowork.md"
+    guide_summary: "guide/cowork.md"
+    guide_full: "cowork/README.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"
+    comparison: "cowork/reference/comparison.md"
+    faq: "cowork/reference/faq.md"
+    prompts: "cowork/prompts/"
+    workflows: "cowork/workflows/"
 
 # ════════════════════════════════════════════════════════════════
 # ONBOARDING MATRIX - Maps user profile → content sections