Update all lessons

01-slash-commands/README.md

@@ -43,6 +43,8 @@ Claude Code provides these built-in slash commands:
 | `/mcp` | Manage MCP server connections and OAuth authentication |
 | `/memory` | Edit `CLAUDE.md` memory files |
 | `/model` | Select or change the AI model |
+| `/plan` | Enter plan mode directly from the prompt |
+| `/remote-env` | Configure remote session environment (claude.ai subscribers) |
 | `/output-style [style]` | Set the output style directly or from a selection menu |
 | `/permissions` | View or update permissions |
 | `/plugin` | Manage Claude Code plugins |
@@ -58,6 +60,7 @@ Claude Code provides these built-in slash commands:
 | `/stats` | Visualize daily usage, session history, streaks, and model preferences |
 | `/status` | Open the Settings interface (Status tab) |
 | `/statusline` | Set up Claude Code's status line UI |
+| `/teleport` | Resume remote session from claude.ai by session ID |
 | `/terminal-setup` | Install Shift+Enter key binding for newlines |
 | `/todos` | List current TODO items |
 | `/usage` | Show plan usage limits and rate limit status |
@@ -160,6 +163,13 @@ allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
 argument-hint: [message]
 description: Create a git commit
 model: claude-3-5-haiku-20241022
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate.sh"
+          once: true
 ---
 
 Create a git commit with message: $ARGUMENTS
@@ -173,7 +183,8 @@ Create a git commit with message: $ARGUMENTS
 | `argument-hint` | Expected arguments for auto-completion | None |
 | `description` | Brief description of the command | Uses first line from prompt |
 | `model` | Specific model to use | Inherits from conversation |
-| `disable-model-invocation` | Prevent SlashCommand tool from calling this | `false` |
+| `hooks` | Component-scoped hooks (PreToolUse, PostToolUse, Stop) | None |
+| `disable-model-invocation` | Prevent Skill tool from calling this | `false` |
 
 ## Plugin Commands
 
@@ -207,9 +218,30 @@ MCP servers can expose prompts as slash commands:
 /mcp__jira__create_issue "Bug title" high
 ```
 
-## SlashCommand Tool
+## MCP Permission Syntax
 
-Claude can programmatically invoke custom slash commands using the SlashCommand tool.
+Control MCP server access using permission syntax in settings:
+
+**Server-level permissions:**
+- `mcp__github` - Access entire GitHub MCP server
+- `mcp__github__*` - Wildcard access to all tools in GitHub server
+- `mcp__github__get_issue` - Specific tool access
+
+**Usage in permissions:**
+```json
+{
+  "permissions": {
+    "blocked": ["mcp__github__*"],
+    "requireConfirmation": ["mcp__jira__create_issue"]
+  }
+}
+```
+
+This allows fine-grained control over which MCP tools Claude can use.
+
+## Skill Tool
+
+Claude can programmatically invoke custom slash commands using the Skill tool.
 
 ### Enabling Programmatic Invocation
 
@@ -232,7 +264,7 @@ disable-model-invocation: true
 Or disable via permissions:
 ```
 /permissions
-# Add to deny rules: SlashCommand
+# Add to deny rules: Skill
 ```
 
 ### Character Budget
@@ -559,12 +591,13 @@ Run the project tests with the following options:
 - **[Subagents](../04-subagents/)** - For complex, delegated tasks
 - **[Plugins](../07-plugins/)** - For bundled command collections
 
-## Resources
+## Additional Resources
 
-- [Claude Code Slash Commands Documentation](https://code.claude.com/docs/en/slash-commands) - Official documentation
-- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) - Comprehensive blog post
-- [4 Essential Slash Commands I Use in Every Project](../blog-post/4-essential-slash-commands.md) - Practical workflow guide
-- [Markdown Guide](https://www.markdownguide.org/)
+- [Official Slash Commands Documentation](https://code.claude.com/docs/en/slash-commands) - Complete reference
+- [CLI Reference](https://code.claude.com/docs/en/cli-reference) - Command-line options
+- [Memory Guide](../02-memory/) - Persistent context
+- [Skills Guide](../03-skills/) - Auto-invoked capabilities
+- [Markdown Guide](https://www.markdownguide.org/) - Markdown syntax reference
 
 ---
 

02-memory/README.md

@@ -240,6 +240,48 @@ graph TD
     E -->|imports| F["@docs/api-standards.md"]
 ```
 
+## Modular Rules System
+
+Create organized, path-specific rules using the `.claude/rules/` directory structure:
+
+```
+your-project/
+├── .claude/
+│   ├── CLAUDE.md
+│   └── rules/
+│       ├── code-style.md
+│       ├── testing.md
+│       └── security.md
+```
+
+### Path-Specific Rules with YAML Frontmatter
+
+Define rules that apply only to specific file paths:
+
+```markdown
+---
+paths: src/api/**/*.ts
+---
+
+# API Development Rules
+
+- All API endpoints must include input validation
+- Use Zod for schema validation
+- Document all parameters and response types
+- Include error handling for all operations
+```
+
+**Glob Pattern Examples:**
+
+- `**/*.ts` - All TypeScript files
+- `src/**/*` - All files under src/
+- `src/**/*.{ts,tsx}` - Multiple extensions
+- `{src,lib}/**/*.ts, tests/**/*.test.ts` - Multiple patterns
+
+### Symlinks Support
+
+Rules in `.claude/rules/` support symlinks for file references and external documentation.
+
 ## Memory Locations Table
 
 | Location | Scope | Priority | Shared | Access | Best For |
@@ -249,6 +291,7 @@ graph TD
 | `C:\ProgramData\ClaudeCode\CLAUDE.md` (Windows) | Enterprise | Highest | Organization | System | Corporate guidelines |
 | `./CLAUDE.md` | Project | High | Team | Git | Team standards, shared architecture |
 | `./.claude/CLAUDE.md` | Project | High | Team | Git | Alternative project location |
+| `./.claude/rules/` | Project Rules | High | Team | Git | Path-specific, modular rules |
 | `./subdir/CLAUDE.md` | Directory | Medium | Team | Git | Directory-specific rules |
 | `~/.claude/CLAUDE.md` | Personal | Low | Individual | Filesystem | Personal preferences |
 | `./CLAUDE.local.md` | Project Local | Deprecated | Individual | Git (ignored) | Personal project notes (deprecated) |
@@ -849,12 +892,11 @@ Claude will prompt you to choose which memory file to update.
 
 ## Official Documentation
 
-This guide is based on official Claude Code documentation. For the most up-to-date information, refer to:
+For the most up-to-date information, refer to the official Claude Code documentation:
 
-- **[Memory Documentation](https://code.claude.com/docs/en/memory.md)** - Complete memory system reference
-- **[Slash Commands Reference](https://code.claude.com/docs/en/slash-commands.md)** - All built-in commands including `/init` and `/memory`
-- **[Quickstart Guide](https://code.claude.com/docs/en/quickstart.md)** - Getting started with Claude Code
-- **[Documentation Map](https://code.claude.com/docs/en/claude_code_docs_map.md)** - Complete documentation index
+- **[Memory Documentation](https://code.claude.com/docs/en/memory)** - Complete memory system reference
+- **[Slash Commands Reference](https://code.claude.com/docs/en/slash-commands)** - All built-in commands including `/init` and `/memory`
+- **[CLI Reference](https://code.claude.com/docs/en/cli-reference)** - Command-line interface documentation
 
 ### Key Technical Details from Official Docs
 

03-skills/README.md

@@ -78,11 +78,27 @@ my-skill/
     └── template.txt
 ```
 
-### SKILL.md Format
+### SKILL.md Format with Full Metadata
+
 ```yaml
 ---
 name: your-skill-name
 description: Brief description of what this Skill does and when to use it
+context: fork              # Optional: run in isolated sub-agent context
+agent: Explore             # Optional: which agent type (with context: fork)
+user-invocable: true       # Optional: default true, hide from slash menu if false
+disable-model-invocation: false  # Optional: prevent auto-invocation
+allowed-tools:             # Optional: restrict tool access
+  - Read
+  - Grep
+  - Glob
+hooks:                     # Optional: component-scoped hooks
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate.sh"
+          once: true
 ---
 
 # Your Skill Name
@@ -94,27 +110,71 @@ Provide clear, step-by-step guidance for Claude.
 Show concrete examples of using this Skill.
 ```
 
-### Requirements
+### Required Fields
 - **name**: lowercase letters, numbers, hyphens only (max 64 characters)
 - **description**: what the Skill does AND when to use it (max 1024 characters)
 
-### Advanced Feature: Restrict Tool Access
+### Optional Fields
+
+#### Tool Restriction: `allowed-tools`
+
 Limit which tools Claude can use with a Skill:
 
 ```yaml
----
-name: safe-file-reader
-description: Read files without making changes. Use when users need read-only file access or want to search files safely.
-allowed-tools: Read, Grep, Glob
----
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
 ```
 
-**Use cases for `allowed-tools`:**
+**Use cases:**
 - **Read-only Skills**: Prevent accidental file modifications
 - **Security-sensitive workflows**: Limit tool access for sensitive operations
-- **Limited scope Skills**: Restrict to specific tools (e.g., data analysis only)
+- **Limited scope Skills**: Restrict to specific tools
 
-**Note**: If `allowed-tools` isn't specified, Claude will ask for permission as normal.
+If `allowed-tools` isn't specified, Claude will request permission as normal.
+
+#### Execution Context: `context`
+
+Run a skill in an isolated subagent context:
+
+```yaml
+context: fork              # Run in isolated context
+agent: Explore             # Use specific agent type
+```
+
+This creates a dedicated subagent for the skill with its own context and state.
+
+#### Visibility Control
+
+Control skill visibility and invocation:
+
+```yaml
+user-invocable: false                 # Hide from slash menu
+disable-model-invocation: false       # Block auto-invocation
+```
+
+| Setting | Slash Menu | Skill Tool | Auto-discovery |
+|---------|------------|------------|----------------|
+| `user-invocable: true` (default) | Visible | Allowed | Yes |
+| `user-invocable: false` | Hidden | Allowed | Yes |
+| `disable-model-invocation: true` | Visible | Blocked | Yes |
+
+#### Hooks in Skills
+
+Add component-scoped hooks to your skill:
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate.sh"
+          once: true
+```
+
+Supported events: `PreToolUse`, `PostToolUse`, `Stop`
 
 ## Managing Skills
 
@@ -1005,6 +1065,19 @@ graph TD
     I --> J["Return Results"]
 ```
 
+## Skills with Subagents
+
+Skills can be automatically loaded with subagents, enabling specialized task delegation:
+
+```yaml
+# In subagent definition
+skills: pr-review, security-check
+```
+
+This allows subagents to access and invoke specific skills autonomously.
+
+**Note**: Built-in agents (Explore, Plan, general-purpose) do not have access to user-defined skills.
+
 ## Skill vs Other Features
 
 ```mermaid
@@ -1221,11 +1294,11 @@ After copying skills:
 4. Test by copying to skills directory
 5. Refine based on usage
 
-## Related Concepts Links
+## Additional Resources
 
-- **Slash Commands** - User-initiated shortcuts for specific tasks
-- **Subagents** - Delegated AI agents for task distribution
-- **Memory** - Persistent context across conversation sessions
-- **MCP (Model Context Protocol)** - Real-time access to external data sources
-- **Claude Code** - AI CLI for automated development workflows
-- **Skill Metadata** - YAML frontmatter that defines skill activation rules
+- [Official Skills Documentation](https://code.claude.com/docs/en/skills)
+- [Slash Commands Guide](../01-slash-commands/) - User-initiated shortcuts
+- [Subagents Guide](../04-subagents/) - Delegated AI agents
+- [Memory Guide](../02-memory/) - Persistent context
+- [MCP (Model Context Protocol)](../05-mcp/) - Real-time external data
+- [Hooks Guide](../06-hooks/) - Event-driven automation

04-subagents/README.md

@@ -82,6 +82,12 @@ tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
 model: sonnet  # Optional - specify model alias or 'inherit'
 permissionMode: default  # Optional - permission mode
 skills: skill1, skill2  # Optional - skills to auto-load
+hooks:  # Optional - component-scoped hooks
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/security-check.sh"
 ---
 
 Your subagent's system prompt goes here. This can be multiple paragraphs
@@ -99,6 +105,7 @@ to solving problems.
 | `model` | No | Model to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to configured subagent model |
 | `permissionMode` | No | `default`, `acceptEdits`, `bypassPermissions`, `plan`, `ignore` |
 | `skills` | No | Comma-separated list of skills to auto-load |
+| `hooks` | No | Component-scoped hooks (PreToolUse, PostToolUse, Stop) |
 
 ### Tool Configuration Options
 
@@ -130,7 +137,7 @@ tools: Read, Bash(npm:*), Bash(test:*)
 
 ### CLI-Based Configuration
 
-Define subagents for a single session using the `--agents` flag:
+Define subagents for a single session using the `--agents` flag with JSON format:
 
 ```bash
 claude --agents '{
@@ -143,6 +150,28 @@ claude --agents '{
 }'
 ```
 
+**JSON Format for `--agents` flag:**
+
+```json
+{
+  "agent-name": {
+    "description": "Required: when to invoke this agent",
+    "prompt": "Required: system prompt for the agent",
+    "tools": ["Optional", "array", "of", "tools"],
+    "model": "optional: sonnet|opus|haiku"
+  }
+}
+```
+
+**Priority of Agent Definitions:**
+
+Agent definitions are loaded with this priority order (first match wins):
+1. **CLI-defined** - `--agents` flag (session-specific)
+2. **User-level** - `~/.claude/agents/` (all projects)
+3. **Project-level** - `.claude/agents/` (current project)
+
+This allows CLI definitions to override both user and project agents for a single session.
+
 ---
 
 ## Built-in Subagents
@@ -180,10 +209,10 @@ Claude Code includes three built-in subagents that are always available:
 
 **When used**: When searching/understanding code without making changes.
 
-**Thoroughness Levels**:
-- **Quick** - Fast searches with minimal exploration
-- **Medium** - Moderate exploration, balanced speed and thoroughness
-- **Very thorough** - Comprehensive analysis across multiple locations and naming conventions
+**Thoroughness Levels** - Specify the depth of exploration:
+- **"quick"** - Fast searches with minimal exploration, good for finding specific patterns
+- **"medium"** - Moderate exploration, balanced speed and thoroughness, default approach
+- **"very thorough"** - Comprehensive analysis across multiple locations and naming conventions, may take longer
 
 ---
 
@@ -667,12 +696,14 @@ graph TD
 
 ---
 
-## Resources
+## Additional Resources
 
 - [Official Subagents Documentation](https://code.claude.com/docs/en/sub-agents)
+- [CLI Reference](https://code.claude.com/docs/en/cli-reference) - `--agents` flag and other CLI options
 - [Plugins Guide](../07-plugins/) - For bundling agents with other features
 - [Skills Guide](../03-skills/) - For auto-invoked capabilities
 - [Memory Guide](../02-memory/) - For persistent context
+- [Hooks Guide](../06-hooks/) - For event-driven automation
 
 ---
 

05-mcp/README.md

@@ -51,6 +51,49 @@ graph TB
     F -->|Docs| K["Google Drive"]
 ```
 
+## MCP Installation Methods
+
+Claude Code supports multiple transport protocols for MCP server connections:
+
+### HTTP Transport (Recommended)
+
+```bash
+# Basic HTTP connection
+claude mcp add --transport http notion https://mcp.notion.com/mcp
+
+# HTTP with authentication header
+claude mcp add --transport http secure-api https://api.example.com/mcp \
+  --header "Authorization: Bearer your-token"
+```
+
+### Stdio Transport (Local)
+
+For locally running MCP servers:
+
+```bash
+# Local Node.js server
+claude mcp add --transport stdio myserver -- npx @myorg/mcp-server
+
+# With environment variables
+claude mcp add --transport stdio myserver --env KEY=value -- npx server
+```
+
+### SSE Transport (Deprecated)
+
+Server-Sent Events transport is deprecated but still supported:
+
+```bash
+claude mcp add --transport sse legacy-server https://example.com/sse
+```
+
+### Windows-Specific Note
+
+On native Windows (not WSL), use `cmd /c` for npx commands:
+
+```bash
+claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
+```
+
 ## MCP Setup Process
 
 ```mermaid
@@ -71,12 +114,58 @@ sequenceDiagram
     Claude->>User: ✅ MCP connected!
 ```
 
-## Installation
+## MCP Scopes
 
-Copy the appropriate configuration to your project's `.claude/` directory:
+MCP configurations can be stored at different scopes with varying levels of sharing:
+
+| Scope | Location | Description | Shared With | Requires Approval |
+|-------|----------|-------------|-------------|------------------|
+| **Local** (default) | `~/.claude.json` | Private to current user | Just you | No |
+| **Project** | `.mcp.json` | Checked into git repository | Team members | Yes (first use) |
+| **User** | `~/.claude.json` | Available across all projects | Just you | No |
+
+### Using Project Scope
+
+Store project-specific MCP configurations in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.github.com/mcp"
+    }
+  }
+}
+```
+
+Team members will see an approval prompt on first use of project MCPs.
+
+## MCP Configuration Management
+
+### Adding MCP Servers
 
 ```bash
-cp github-mcp.json /path/to/your/project/.claude/mcp.json
+# Add HTTP-based server
+claude mcp add --transport http github https://api.github.com/mcp
+
+# Add local stdio server
+claude mcp add --transport stdio database -- npx @company/db-server
+
+# List all MCP servers
+claude mcp list
+
+# Get details on specific server
+claude mcp get github
+
+# Remove an MCP server
+claude mcp remove github
+
+# Reset project-specific approval choices
+claude mcp reset-project-choices
+
+# Import from Claude Desktop
+claude mcp add-from-claude-desktop
 ```
 
 ## Available MCP Servers Table
@@ -158,6 +247,29 @@ export GITHUB_TOKEN="your_github_token"
 cp github-mcp.json ~/.claude/mcp.json
 ```
 
+### Environment Variable Expansion in Configuration
+
+MCP configurations support environment variable expansion with fallback defaults:
+
+```json
+{
+  "mcpServers": {
+    "api-server": {
+      "type": "http",
+      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
+      "headers": {
+        "Authorization": "Bearer ${API_KEY}",
+        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
+      }
+    }
+  }
+}
+```
+
+Variables are expanded at runtime:
+- `${VAR}` - Uses environment variable, error if not set
+- `${VAR:-default}` - Uses environment variable, falls back to default if not set
+
 ### Example 2: Database MCP Setup
 
 **Configuration:**
@@ -345,6 +457,53 @@ Then reference them in MCP config:
 }
 ```
 
+## Claude as MCP Server
+
+Claude Code itself can act as an MCP server for other applications:
+
+```bash
+claude mcp serve
+```
+
+This starts Claude Code in MCP server mode, allowing other MCP clients to connect and use Claude's capabilities as a service.
+
+## Managed MCP Configuration (Enterprise)
+
+For enterprise deployments, MCP servers can be managed centrally via configuration files:
+
+**Location:**
+- macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`
+- Linux: `~/.config/ClaudeCode/managed-mcp.json`
+- Windows: `%APPDATA%\ClaudeCode\managed-mcp.json`
+
+**Features:**
+- Allowlist/denylist controls
+- Restrict by server name, command, or URL
+- Organization-wide MCP policies
+- Prevents unauthorized server connections
+
+**Example configuration:**
+
+```json
+{
+  "allowlist": [
+    {
+      "serverName": "github",
+      "serverUrl": "https://api.github.com/mcp"
+    },
+    {
+      "serverName": "company-internal",
+      "serverCommand": "company-mcp-server"
+    }
+  ],
+  "denylist": [
+    {
+      "serverName": "untrusted-*"
+    }
+  ]
+}
+```
+
 ## Best Practices
 
 ### Security Considerations
@@ -511,9 +670,9 @@ export GITHUB_TOKEN="your_token"
 
 ## Additional Resources
 
+- [Official MCP Documentation](https://code.claude.com/docs/en/mcp)
+- [MCP Protocol Specification](https://spec.modelcontextprotocol.io/)
 - [MCP GitHub Repository](https://github.com/modelcontextprotocol/servers)
-- [MCP Protocol Specification](https://modelcontextprotocol.io)
-- [Claude Code MCP Guide](https://docs.claude.com/en/docs/claude-code/mcp)
 - [Available MCP Servers](https://github.com/modelcontextprotocol/servers)
+- [Claude Code CLI Reference](https://code.claude.com/docs/en/cli-reference)
 - [Claude API Documentation](https://docs.anthropic.com)
-- [Environment Variables Setup Guide](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables)

06-hooks/README.md

@@ -77,7 +77,7 @@ Claude Code supports **9 hook events**:
 | **SubagentStop** | Subagent finishes | No | Yes | Subagent validation |
 | **PreCompact** | Before compact operation | Yes (manual/auto) | No | Pre-compact actions |
 | **SessionStart** | Session begins/resumes | Yes (startup/resume/clear/compact) | No | Environment setup |
-| **SessionEnd** | Session ends | No | No | Cleanup |
+| **SessionEnd** | Session ends (cleanup only) | No | No | Cleanup, final logging |
 
 ### PreToolUse
 
@@ -202,6 +202,84 @@ fi
 exit 0
 ```
 
+### SessionEnd
+
+Runs when session ends to perform cleanup or final logging. Cannot block termination.
+
+**Reason field values:**
+- `clear` - User cleared the session
+- `logout` - User logged out
+- `prompt_input_exit` - User exited via prompt input
+- `other` - Other reason
+
+**Configuration:**
+```json
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Notification Event
+
+Updated matchers for notification events:
+- `permission_prompt` - Permission request notification
+- `idle_prompt` - Idle state notification
+- `auth_success` - Authentication success
+- `elicitation_dialog` - Dialog shown to user
+
+## Component-Scoped Hooks
+
+Hooks can be attached to specific components (skills, agents, commands) in their frontmatter:
+
+**In SKILL.md, agent.md, or command.md:**
+
+```yaml
+---
+name: secure-operations
+description: Perform operations with security checks
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/check.sh"
+          once: true  # Only run once per session
+---
+```
+
+**Supported events for component hooks:** `PreToolUse`, `PostToolUse`, `Stop`
+
+This allows defining hooks directly in the component that uses them, keeping related code together.
+
+## PermissionRequest Event
+
+Handles permission requests with custom output format:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PermissionRequest",
+    "decision": {
+      "behavior": "allow|deny",
+      "updatedInput": {},
+      "message": "Custom message",
+      "interrupt": false
+    }
+  }
+}
+```
+
 ## Hook Input and Output
 
 ### JSON Input (via stdin)
@@ -660,6 +738,35 @@ if __name__ == "__main__":
 
 > **Note:** Anthropic hasn't released an official offline tokenizer. Both methods are approximations. The transcript includes user prompts, Claude's responses, and tool outputs, but NOT system prompts or internal context.
 
+## Plugin Hooks
+
+Plugins can include hooks in their `hooks/hooks.json` file:
+
+**File:** `plugins/hooks/hooks.json`
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Environment Variables in Plugin Hooks:**
+- `${CLAUDE_PLUGIN_ROOT}` - Path to the plugin directory
+
+This allows plugins to include custom validation and automation hooks.
+
 ## MCP Tool Hooks
 
 MCP tools follow the pattern `mcp__<server>__<tool>`:
@@ -845,9 +952,13 @@ Edit `~/.claude/settings.json` or `.claude/settings.json` with the hook configur
 
 - **[Checkpoints and Rewind](../08-checkpoints/)** - Save and restore conversation state
 - **[Slash Commands](../01-slash-commands/)** - Create custom slash commands
+- **[Skills](../03-skills/)** - Reusable autonomous capabilities
+- **[Subagents](../04-subagents/)** - Delegated task execution
 - **[Plugins](../07-plugins/)** - Bundled extension packages
 - **[Advanced Features](../09-advanced-features/)** - Explore advanced Claude Code capabilities
 
-## Resources
+## Additional Resources
 
-- **Official Documentation**: [code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)
+- **[Official Hooks Documentation](https://code.claude.com/docs/en/hooks)** - Complete hooks reference
+- **[CLI Reference](https://code.claude.com/docs/en/cli-reference)** - Command-line interface documentation
+- **[Memory Guide](../02-memory/)** - Persistent context configuration

07-plugins/README.md

@@ -66,47 +66,29 @@ sequenceDiagram
 
 ## Plugin Definition Structure
 
-```yaml
----
-name: plugin-name
-version: "1.0.0"
-description: "What this plugin does"
-author: "Your Name"
-license: MIT
+Plugin manifest uses JSON format in `.claude-plugin/plugin.json`:
 
-# Plugin metadata
-tags:
-  - category
-  - use-case
-
-# Requirements
-requires:
-  - claude-code: ">=1.0.0"
-
-# Components bundled
-components:
-  - type: commands
-    path: commands/
-  - type: agents
-    path: agents/
-  - type: mcp
-    path: mcp/
-  - type: hooks
-    path: hooks/
-
-# Configuration
-config:
-  auto_load: true
-  enabled_by_default: true
----
+```json
+{
+  "name": "my-first-plugin",
+  "description": "A greeting plugin",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name"
+  },
+  "homepage": "https://example.com",
+  "repository": "https://github.com/user/repo",
+  "license": "MIT"
+}
 ```
 
 ## Plugin Structure Example
 
 ```
 my-plugin/
-├── plugin.yaml
-├── commands/
+├── .claude-plugin/
+│   └── plugin.json       # NOT plugin.yaml
+├── commands/             # Outside .claude-plugin
 │   ├── task-1.md
 │   ├── task-2.md
 │   └── workflows/
@@ -114,12 +96,13 @@ my-plugin/
 │   ├── specialist-1.md
 │   ├── specialist-2.md
 │   └── configs/
-├── mcp/
-│   ├── mcp-config.json
-│   └── servers/
+├── skills/
+│   ├── skill-1.md
+│   └── skill-2.md
 ├── hooks/
-│   ├── pre-deploy.js
-│   └── post-merge.js
+│   └── hooks.json
+├── .mcp.json
+├── .lsp.json             # NEW: LSP server config
 ├── templates/
 │   └── issue-template.md
 ├── scripts/
@@ -132,33 +115,48 @@ my-plugin/
     └── plugin.test.js
 ```
 
+## LSP Server Configuration
+
+Plugins can include Language Server Protocol (LSP) support via `.lsp.json`:
+
+```json
+{
+  "go": {
+    "command": "gopls",
+    "args": ["serve"],
+    "extensionToLanguage": {
+      ".go": "go"
+    }
+  }
+}
+```
+
+## Standalone vs Plugin Approach
+
+| Approach | Command Names | Configuration | Best For |
+|----------|---------------|---|---|
+| **Standalone** | `/hello` | Manual setup in CLAUDE.md | Personal, project-specific |
+| **Plugins** | `/plugin-name:hello` | Automated via plugin.json | Sharing, distribution, team use |
+
+Use **standalone slash commands** for quick personal workflows. Use **plugins** when you want to bundle multiple features, share with a team, or publish for distribution.
+
 ## Practical Examples
 
 ### Example 1: PR Review Plugin
 
-**File:** `plugin.yaml`
+**File:** `.claude-plugin/plugin.json`
 
-```yaml
----
-name: pr-review
-version: "1.0.0"
-description: Complete PR review workflow with security, testing, and docs
-author: Anthropic
-tags:
-  - code-review
-  - quality
-  - security
-
-components:
-  - type: commands
-    path: commands/
-  - type: agents
-    path: agents/
-  - type: mcp
-    path: mcp/
-  - type: hooks
-    path: hooks/
----
+```json
+{
+  "name": "pr-review",
+  "version": "1.0.0",
+  "description": "Complete PR review workflow with security, testing, and docs",
+  "author": {
+    "name": "Anthropic"
+  },
+  "repository": "https://github.com/anthropic/pr-review",
+  "license": "MIT"
+}
 ```
 
 **File:** `commands/review-pr.md`
@@ -366,14 +364,29 @@ graph TD
 | **Specialized Analysis** | ❌ Use Subagent | Create manually or use skill |
 | **Live Data Access** | ❌ Use MCP | Standalone, don't bundle |
 
+## Testing a Plugin
+
+Before publishing, test your plugin locally using the CLI flag:
+
+```bash
+claude --plugin-dir ./my-plugin
+```
+
+This launches Claude Code with your plugin loaded, allowing you to:
+- Verify all slash commands are available
+- Test subagents and agents function correctly
+- Confirm MCP servers connect properly
+- Validate hook execution
+- Check for any configuration errors
+
 ## Publishing a Plugin
 
 **Steps to publish:**
 
 1. Create plugin structure with all components
-2. Write `plugin.yaml` manifest
+2. Write `.claude-plugin/plugin.json` manifest
 3. Create `README.md` with documentation
-4. Test locally with `/plugin install ./my-plugin`
+4. Test locally with `claude --plugin-dir ./my-plugin`
 5. Submit to plugin marketplace
 6. Get reviewed and approved
 7. Published on marketplace
@@ -587,10 +600,10 @@ The following Claude Code features work together with plugins:
 
 ## Additional Resources
 
-- [Claude Code Documentation](https://docs.claude.com/claude-code)
-- [Plugin Marketplace](https://plugins.claude.com)
-- [Official Plugin Examples](https://github.com/anthropic/claude-plugins)
-- [Plugin Development Guide](https://docs.claude.com/plugins/development)
+- [Official Plugins Documentation](https://code.claude.com/docs/en/plugins)
+- [Discover Plugins](https://code.claude.com/docs/en/discover-plugins)
+- [Plugin Marketplaces](https://code.claude.com/docs/en/plugin-marketplaces)
+- [Plugins Reference](https://code.claude.com/docs/en/plugins-reference)
 - [MCP Server Reference](https://spec.modelcontextprotocol.io/)
 - [Subagent Configuration Guide](../04-subagents/README.md)
 - [Hook System Reference](../06-hooks/README.md)

08-checkpoints/README.md

@@ -22,49 +22,38 @@ Checkpoints are invaluable when exploring different approaches, recovering from
 | **Rewind** | Return to a previous checkpoint, discarding subsequent changes |
 | **Branch Point** | Checkpoint from which multiple approaches are explored |
 
-## Commands
+## Accessing Checkpoints
 
-All checkpoint operations are performed using the `/checkpoint` command:
+You can access and manage checkpoints in two primary ways:
+
+### Using Keyboard Shortcut
+Press `Esc` twice (`Esc` + `Esc`) to open the checkpoint interface and browse saved checkpoints.
+
+### Using Slash Command
+Use the `/rewind` command for quick access:
 
 ```bash
-# Create checkpoint
-/checkpoint save "Before refactoring"
-
-# List checkpoints
-/checkpoint list
-
-# Rewind to checkpoint
-/checkpoint rewind "Before refactoring"
-
-# Compare checkpoints
-/checkpoint diff checkpoint-1 checkpoint-2
-
-# Delete checkpoint
-/checkpoint delete checkpoint-1
-
-# Export checkpoint
-/checkpoint export "name" ~/checkpoints/backup.json
+# Open rewind interface
+/rewind
 ```
 
-## Creating Checkpoints
+## Rewind Options
 
-### Automatic Checkpoints
-Claude Code automatically creates checkpoints at key moments:
-- Before major refactoring operations
-- Before potentially destructive commands
-- At regular intervals during long sessions
-- Before running tests or builds
+When you rewind, you can choose what to restore:
 
-### Manual Checkpoints
-Create checkpoints explicitly:
+- **Conversation only** - Restore chat history and context, keep current code
+- **Code only** - Restore file changes, keep current conversation
+- **Both** - Restore both conversation and code to the checkpoint state
 
-```
-User: /checkpoint save "Before API refactor"
-```
+## Automatic Checkpoints
 
-```
-User: /checkpoint create pre-deployment
-```
+Claude Code automatically creates checkpoints for you:
+
+- **Every user prompt** - A new checkpoint is created with each user input
+- **Persistent** - Checkpoints persist across sessions
+- **Auto-cleaned** - Checkpoints are automatically cleaned up after 30 days (configurable)
+
+This means you can always rewind to any previous point in your conversation, from a few minutes ago to days before.
 
 ## Use Cases
 
@@ -77,40 +66,17 @@ User: /checkpoint create pre-deployment
 
 ## Using Checkpoints
 
-### List Checkpoints
-View all available checkpoints:
+### Viewing and Rewinding
 
-```
-User: /checkpoint list
-```
+Press `Esc` twice or use `/rewind` to open the checkpoint browser. You'll see a list of all available checkpoints with timestamps. Select any checkpoint to rewind to that state.
 
-Output:
-```
-Checkpoints:
-1. [2025-11-08 10:30:15] Auto: Before file edit
-2. [2025-11-08 10:45:22] Manual: Before API refactor
-3. [2025-11-08 11:02:10] Auto: Before git commit
-4. [2025-11-08 11:15:45] Manual: pre-deployment
-```
+### Checkpoint Details
 
-### Rewind to Checkpoint
-Return to a previous checkpoint:
-
-```
-User: /checkpoint rewind 2
-```
-
-Or by name:
-```
-User: /checkpoint rewind "Before API refactor"
-```
-
-### Compare Checkpoints
-See what changed between checkpoints:
-
-```
-User: /checkpoint diff 2 4
-```
+Each checkpoint shows:
+- Timestamp of when it was created
+- Files that were modified
+- Number of messages in the conversation
+- Tools that were used
 
 ## Practical Examples
 
@@ -120,21 +86,15 @@ User: /checkpoint diff 2 4
 User: Let's add a caching layer to the API
 
 Claude: I'll add Redis caching to your API endpoints...
-[Makes changes]
-
-User: /checkpoint save "Redis approach"
+[Makes changes at checkpoint A]
 
 User: Actually, let's try in-memory caching instead
 
-Claude: I'll rewind and implement in-memory caching...
-[Uses /checkpoint rewind to undo Redis changes]
-[Implements in-memory caching]
+Claude: I'll rewind to explore a different approach...
+[User presses Esc+Esc and rewinds to checkpoint A]
+[Implements in-memory caching at checkpoint B]
 
-User: /checkpoint save "In-memory approach"
-
-User: /checkpoint diff "Redis approach" "In-memory approach"
-
-Claude: Here are the differences between the two approaches...
+User: Now I can compare both approaches
 ```
 
 ### Example 2: Recovering from Mistakes
@@ -147,8 +107,8 @@ Claude: I'll refactor the authentication module...
 
 User: Wait, that broke the OAuth integration. Let's go back.
 
-Claude: I'll rewind to before the refactoring...
-/checkpoint rewind "Before auth refactor"
+Claude: I'll help you rewind to before the refactoring...
+[User presses Esc+Esc and selects the checkpoint before the refactor]
 
 User: Let's try a more conservative approach this time
 ```
@@ -156,189 +116,87 @@ User: Let's try a more conservative approach this time
 ### Example 3: Safe Experimentation
 
 ```
-User: /checkpoint save "Working state before experiment"
-
 User: Let's try rewriting this in a functional style
+[Creates checkpoint before experiment]
 
 Claude: [Makes experimental changes]
 
 User: The tests are failing. Let's rewind.
+[User presses Esc+Esc and rewinds to the checkpoint]
 
-Claude: /checkpoint rewind "Working state before experiment"
+Claude: I've rewound the changes. Let's try a different approach.
 ```
 
-### Example 4: Comparing Solutions
+### Example 4: Branching Approaches
 
 ```
 User: I want to compare two database designs
+[Takes note of checkpoint - call it "Start"]
 
 Claude: I'll create the first design...
 [Implements Schema A]
 
-User: /checkpoint save "Schema A"
+User: Now let me go back and try the second approach
+[User presses Esc+Esc and rewinds to "Start"]
 
-Claude: /checkpoint rewind to start
+Claude: Now I'll implement Schema B...
 [Implements Schema B]
 
-User: /checkpoint save "Schema B"
-
-User: /checkpoint compare "Schema A" "Schema B"
-
-Claude: Here's a comparison of both schemas:
-- Schema A uses normalization...
-- Schema B uses denormalization...
+User: Great! Now I have both schemas to choose from
 ```
 
-## Checkpoint Management
+## Checkpoint Retention
 
-### View Checkpoint Details
+Claude Code automatically manages your checkpoints:
+
+- Checkpoints are created automatically with every user prompt
+- Old checkpoints are retained for up to 30 days
+- You can configure the retention period in your settings
+- Checkpoints are cleaned up automatically to prevent unlimited storage growth
+
+## Workflow Patterns
+
+### Branching Strategy for Exploration
+
+When exploring multiple approaches:
 
 ```
-User: /checkpoint show 2
+1. Start with initial implementation → Checkpoint A
+2. Try Approach 1 → Checkpoint B
+3. Rewind to Checkpoint A
+4. Try Approach 2 → Checkpoint C
+5. Compare results from B and C
+6. Choose best approach and continue
 ```
 
-Output:
-```
-Checkpoint #2: "Before API refactor"
-Created: 2025-11-08 10:45:22
-Files modified: 5
-- src/api/endpoints.ts
-- src/api/middleware.ts
-- src/utils/cache.ts
-- tests/api.test.ts
-- package.json
+### Safe Refactoring Pattern
 
-Message count: 23
-Tools used: Read, Edit, Bash
-```
-
-### Delete Checkpoints
+When making significant changes:
 
 ```
-User: /checkpoint delete 1
-```
-
-Or delete all:
-```
-User: /checkpoint clear
-```
-
-### Export Checkpoints
-
-Save checkpoint for later use:
-```
-User: /checkpoint export "Before API refactor" ~/checkpoints/api-refactor.json
-```
-
-### Import Checkpoints
-
-Restore from saved checkpoint:
-```
-User: /checkpoint import ~/checkpoints/api-refactor.json
-```
-
-## Advanced Usage
-
-### Branching Strategy
-
-```markdown
-Main conversation
-├─ Checkpoint 1: "Initial state"
-│
-├─ Branch A: Redis implementation
-│  ├─ Checkpoint 2: "Redis complete"
-│  └─ Checkpoint 3: "Redis with clustering"
-│
-└─ Branch B: In-memory implementation
-   ├─ Checkpoint 4: "In-memory complete"
-   └─ Checkpoint 5: "In-memory optimized"
-```
-
-### Checkpoint Scripts
-
-Create automated checkpoint workflows:
-
-```bash
-#!/bin/bash
-# create-safe-checkpoint.sh
-
-# Create checkpoint
-echo "/checkpoint save \"Safe point - $(date +%Y%m%d-%H%M%S)\"" | claude-code
-
-# Run risky operation
-echo "$1" | claude-code
-
-# Check if successful
-if [ $? -ne 0 ]; then
-  echo "/checkpoint rewind last" | claude-code
-  echo "Operation failed, reverted to checkpoint"
-fi
-```
-
-### Checkpoint Hooks
-
-Automatically create checkpoints on events:
-
-```json
-{
-  "hooks": {
-    "PreToolUse:Edit": "~/.claude/hooks/create-checkpoint.sh",
-    "PreCommit": "~/.claude/hooks/checkpoint-before-commit.sh"
-  }
-}
-```
-
-Example hook:
-```bash
-#!/bin/bash
-# ~/.claude/hooks/create-checkpoint.sh
-
-FILE=$1
-TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S")
-
-# Create checkpoint before editing important files
-if [[ "$FILE" =~ (config|database|auth|api) ]]; then
-  echo "Creating checkpoint before editing $FILE"
-  # Trigger checkpoint creation
-fi
+1. Current state → Checkpoint (auto)
+2. Start refactoring
+3. Run tests
+4. If tests pass → Continue working
+5. If tests fail → Rewind and try different approach
 ```
 
 ## Best Practices
 
-### When to Create Checkpoints
+Since checkpoints are created automatically, you can focus on your work without worrying about manually saving state. However, keep these practices in mind:
 
-✅ **Do create checkpoints:**
-- Before major refactoring
-- Before trying experimental approaches
-- Before potentially breaking changes
-- At the end of successful feature implementations
-- Before switching to a different task
+### Using Checkpoints Effectively
 
-❌ **Don't create checkpoints:**
-- After every single change (too granular)
-- For trivial changes (typo fixes, formatting)
-- Without descriptive names
+✅ **Do:**
+- Review available checkpoints before rewinding
+- Use rewind when you want to explore different directions
+- Keep checkpoints to compare different approaches
+- Understand what each rewind option does (conversation, code, or both)
 
-### Naming Conventions
-
-Good checkpoint names:
-- ✅ "Before auth refactor"
-- ✅ "Working state - all tests passing"
-- ✅ "Pre-deployment v1.2.0"
-- ✅ "Schema A - normalized design"
-
-Poor checkpoint names:
-- ❌ "checkpoint1"
-- ❌ "temp"
-- ❌ "test"
-- ❌ "backup"
-
-### Checkpoint Hygiene
-
-- **Limit active checkpoints**: Keep 5-10 meaningful checkpoints
-- **Delete old checkpoints**: Remove outdated ones regularly
-- **Use descriptive names**: Make it easy to identify later
-- **Document major checkpoints**: Add notes about what was accomplished
+❌ **Don't:**
+- Rely on checkpoints alone for code preservation
+- Expect checkpoints to track external file system changes
+- Use checkpoints as a substitute for git commits
 
 ## Configuration
 
@@ -366,10 +224,11 @@ Configure checkpoint behavior in settings. Here's the comprehensive configuratio
 
 ## Limitations
 
-- Checkpoints are session-specific
-- External changes (outside Claude Code) are not tracked
-- Large file changes may increase checkpoint size
-- Some tool states may not be fully restorable
+Checkpoints have the following limitations:
+
+- **Bash command changes NOT tracked** - Operations like `rm`, `mv`, `cp` on the filesystem are not captured in checkpoints
+- **External changes NOT tracked** - Changes made outside Claude Code (in your editor, terminal, etc.) are not captured
+- **Not a replacement for version control** - Use git for permanent, auditable changes to your codebase
 
 ## Troubleshooting
 
@@ -423,41 +282,20 @@ Use both together:
 3. Create checkpoint before git operations
 4. Commit successful checkpoint states to git
 
-## Example Workflows
+## Quick Start Guide
 
-### Safe Refactoring Workflow
+### Basic Workflow
 
-```
-1. /checkpoint save "Before refactoring"
-2. Implement refactoring
-3. Run tests
-4. If tests pass: Commit to git
-5. If tests fail: /checkpoint rewind "Before refactoring"
-```
+1. **Work normally** - Claude Code creates checkpoints automatically
+2. **Want to go back?** - Press `Esc` twice or use `/rewind`
+3. **Choose checkpoint** - Select from the list to rewind
+4. **Select what to restore** - Choose conversation, code, or both
+5. **Continue working** - You're back at that point
 
-### Feature Exploration Workflow
+### Keyboard Shortcuts
 
-```
-1. /checkpoint save "Main branch"
-2. Try approach A
-3. /checkpoint save "Approach A"
-4. /checkpoint rewind "Main branch"
-5. Try approach B
-6. /checkpoint save "Approach B"
-7. /checkpoint compare "Approach A" "Approach B"
-8. Choose best approach and commit
-```
-
-### Emergency Recovery Workflow
-
-```
-1. Notice major issue
-2. /checkpoint list
-3. Identify last known good state
-4. /checkpoint rewind <good-state>
-5. Verify system works
-6. Proceed cautiously
-```
+- **`Esc` + `Esc`** - Open checkpoint browser
+- **`/rewind`** - Alternative way to access checkpoints
 
 ## Related Concepts
 
@@ -467,14 +305,19 @@ Use both together:
 - **[Hooks](../06-hooks/)** - Event-driven automation
 - **[Plugins](../07-plugins/)** - Bundled extension packages
 
+## Additional Resources
+
+- [Official Checkpointing Documentation](https://code.claude.com/docs/en/checkpointing)
+- [Advanced Features Guide](../09-advanced-features/) - Extended thinking and other capabilities
+
 ## Summary
 
-Checkpoints are a powerful feature for safe exploration and experimentation in Claude Code. By combining checkpoints with your development workflow, you can:
+Checkpoints are an automatic feature in Claude Code that lets you safely explore different approaches without fear of losing work. Every user prompt creates a new checkpoint automatically, so you can rewind to any previous point in your session.
 
+Key benefits:
 - Experiment fearlessly with multiple approaches
-- Quickly recover from mistakes without losing work
+- Quickly recover from mistakes
 - Compare different solutions side-by-side
-- Maintain clean, organized development sessions
 - Integrate safely with version control systems
 
-The key to effective checkpoint usage is creating them at meaningful points in your work and using descriptive names that make it easy to find and rewind to the right state when needed.
+Remember: checkpoints are not a replacement for git. Use checkpoints for rapid experimentation and git for permanent code changes.

09-advanced-features/README.md

@@ -63,26 +63,35 @@ Planning mode is a two-phase approach:
 
 ### Activating Planning Mode
 
-**Explicit activation**:
+**Slash command**:
 ```bash
 /plan Implement user authentication system
 ```
 
-**Automatic activation**:
-Claude automatically enters planning mode for complex tasks:
+**CLI flag**:
+```bash
+claude --permission-mode plan
 ```
-User: Refactor the entire API to use microservices architecture
 
-Claude: This is a complex task. Let me create a plan first...
-[Enters planning mode]
+**Set as default**:
+```json
+{
+  "permissions": {
+    "defaultMode": "plan"
+  }
+}
 ```
 
+**Keyboard shortcut**:
+- `Shift + Tab` - Toggle permission modes (including plan)
+- `Alt + M` - Toggle permission modes (Windows/Linux)
+
 ### Benefits of Planning Mode
 
-- **Clear roadmap with time estimates**: Detailed breakdown of implementation steps
-- **Risk assessment**: Identify potential issues before implementation
-- **Systematic task breakdown**: Organized phases and milestones
-- **Opportunity for review and modification**: Approve or adjust the plan before execution
+- **Structured implementation approach**: Detailed breakdown of implementation steps
+- **Review and approval**: Approve or adjust the plan before execution
+- **Risk identification**: Identify potential issues before implementation
+- **Clear phases**: Organized implementation phases and milestones
 
 ### Example: Feature Implementation
 
@@ -169,20 +178,29 @@ Extended thinking is a deliberate, step-by-step reasoning process where Claude:
 
 ### Activating Extended Thinking
 
-**Explicit activation**:
+**Keyboard shortcut**:
+- `Option + T` (macOS) / `Alt + T` (Windows/Linux) - Toggle extended thinking
+
+**Per-request activation**:
 ```bash
-/think Should we use microservices or monolith?
+ultrathink: Should we use microservices or monolith?
 ```
 
 **Automatic activation**:
-For sufficiently complex queries, Claude automatically uses extended thinking.
+- Enabled by default on Sonnet 4.5 and Opus 4.5
+- For sufficiently complex queries, Claude automatically uses extended thinking
+
+**Custom budget**:
+```bash
+export MAX_THINKING_TOKENS=1024
+```
 
 ### Benefits of Extended Thinking
 
-- **Thorough analysis of trade-offs**: Examine pros and cons systematically
+- **Deep reasoning**: Spend more time thinking about complex problems
 - **Better architectural decisions**: Make informed choices with comprehensive evaluation
 - **Consideration of edge cases**: Think through potential issues and scenarios
-- **Systematic evaluation**: Structured approach to complex problem-solving
+- **Thorough analysis**: Structured approach to complex problem-solving
 
 ### Example: Architectural Decision
 
@@ -395,83 +413,79 @@ Claude: [Shows linter output from bg-5002]
 
 ---
 
-## Permission Mode
+## Permission Modes
 
-Permission mode controls what actions Claude can take without explicit approval.
+Permission modes control what actions Claude can take without explicit approval.
 
-### Permission Modes Table
+### Available Permission Modes
 
 | Mode | Description | Use Case |
 |------|-------------|----------|
-| **Unrestricted** | Full access (default) | Active development |
-| **Confirm** | Ask before actions | Learning, pair programming |
-| **Read-only** | Analysis only | Code review |
-| **Custom** | Granular permissions | Fine-tuned control |
+| **default** | Full access, asks for confirmation | Active development |
+| **acceptEdits** | Automatically accepts file edits | Development workflow |
+| **dontAsk** | No confirmation needed | Fully automated |
+| **bypassPermissions** | Bypass all permission checks | Trusted automation |
+| **plan** | Planning mode before implementation | Review before execution |
+| **ignore** | Ignore permission restrictions | Advanced usage |
 
-### Permission Commands
+### Activation Methods
 
+**Keyboard shortcut**:
 ```bash
-/permission readonly      # Code review mode
-/permission confirm       # Learning mode
-/permission unrestricted  # Full automation
+Shift + Tab  # or Alt + M on Windows/Linux
 ```
 
-### Permission Levels
-
-#### 1. Unrestricted Mode (Default)
-Claude can use all tools freely.
-
-```
-User: /permission unrestricted
+**Slash command**:
+```bash
+/plan                  # Enter plan mode
 ```
 
-#### 2. Confirmation Mode
-Claude asks before taking actions.
+**CLI flag**:
+```bash
+claude --permission-mode plan
+```
+
+**Environment variable**:
+```bash
+export CLAUDE_PERMISSION_MODE=plan
+```
+
+### Permission Mode Examples
+
+#### Default Mode
+Claude asks for confirmation on significant actions:
 
 ```
-User: /permission confirm
-
 User: Fix the bug in auth.ts
 
 Claude: I need to modify src/auth.ts to fix the bug.
 The change will update the password validation logic.
 
 Approve this change? (yes/no/show)
-
-User: show
-
-Claude: [Shows the exact changes]
-
-User: yes
-
-Claude: [Makes the change]
 ```
 
-#### 3. Read-Only Mode
-Claude can only read files, not modify them.
+#### Plan Mode
+Review implementation plan before execution:
 
 ```
-User: /permission readonly
+User: /plan Implement user authentication system
 
+Claude: I'll create a plan for implementing authentication.
+
+## Implementation Plan
+[Detailed plan with phases and steps]
+
+Ready to proceed? (yes/no/modify)
+```
+
+#### Accept Edits Mode
+Automatically accept file modifications:
+
+```
+User: acceptEdits
 User: Fix the bug in auth.ts
 
-Claude: I'm in read-only mode. I can analyze the bug and show you the fix, but I cannot modify files.
-
-Here's the bug and suggested fix:
-[Shows analysis and proposed changes]
-```
-
-#### 4. Custom Permission Sets
-
-```json
-{
-  "permissions": {
-    "mode": "custom",
-    "allowed": ["Read", "Grep", "Glob"],
-    "blocked": ["Write", "Edit", "Bash"],
-    "requireConfirmation": ["Git"]
-  }
-}
+Claude: [Makes changes without asking]
 ```
 
 ### Use Cases
@@ -702,31 +716,31 @@ claude-code --new
 
 ### Keyboard Shortcuts
 
-Claude Code supports keyboard shortcuts for efficiency:
+Claude Code supports keyboard shortcuts for efficiency. Here's the complete reference from official docs:
 
-**Basic Navigation and Input:**
-- `Ctrl + R` - Search command history
-- `Tab` - Autocomplete
-- `↑ / ↓` - Command history
-- `Ctrl + L` - Clear screen
+| Shortcut | Description |
+|----------|-------------|
+| `Ctrl+C` | Cancel current input/generation |
+| `Ctrl+D` | Exit Claude Code |
+| `Ctrl+L` | Clear terminal screen |
+| `Ctrl+O` | Toggle verbose output |
+| `Ctrl+R` | Reverse search history |
+| `Ctrl+B` | Background running tasks |
+| `Esc+Esc` | Rewind code/conversation |
+| `Shift+Tab` / `Alt+M` | Toggle permission modes |
+| `Option+P` / `Alt+P` | Switch model |
+| `Option+T` / `Alt+T` | Toggle extended thinking |
 
-**Extended Shortcuts:**
+**Line Editing (standard readline shortcuts):**
 
 | Shortcut | Action |
 |----------|--------|
-| `Ctrl + C` | Cancel current operation |
-| `Ctrl + D` | Exit Claude Code |
-| `Ctrl + L` | Clear screen |
-| `Ctrl + R` | Search command history |
-| `Ctrl + P` | Previous command |
-| `Ctrl + N` | Next command |
 | `Ctrl + A` | Move to line start |
 | `Ctrl + E` | Move to line end |
 | `Ctrl + K` | Cut to end of line |
 | `Ctrl + U` | Cut to start of line |
 | `Ctrl + W` | Delete word backward |
 | `Ctrl + Y` | Paste (yank) |
-| `Ctrl + Z` | Suspend (background) |
 | `Tab` | Autocomplete |
 | `↑ / ↓` | Command history |
 
@@ -796,6 +810,38 @@ User: Deploy to prodcution<Backspace><Backspace>uction
 [Edit in-place before sending]
 ```
 
+### Vim Mode
+
+Enable Vi/Vim keybindings for text editing:
+
+**Activation**:
+- Use `/vim` command or `/config` to enable
+- Mode switching with `Esc` for NORMAL, `i/a/o` for INSERT
+
+**Navigation keys**:
+- `h` / `l` - Move left/right
+- `j` / `k` - Move down/up
+- `w` / `b` / `e` - Move by word
+- `0` / `$` - Move to line start/end
+- `gg` / `G` - Jump to start/end of text
+
+**Text objects**:
+- `iw` / `aw` - Inner/around word
+- `i"` / `a"` - Inner/around quoted string
+- `i(` / `a(` - Inner/around parentheses
+
+### Bash Mode
+
+Execute shell commands directly with `!` prefix:
+
+```bash
+! npm test
+! git status
+! cat src/index.js
+```
+
+Use this for quick command execution without switching contexts.
+
 ---
 
 ## Configuration and Settings
@@ -1033,18 +1079,18 @@ Create `.claude/config.json` in your project:
 
 ---
 
-## Related Concepts
+## Additional Resources
 
-For more information about Claude Code and related features, see:
+For more information about Claude Code and related features:
 
-- [Main Claude Code Guide](../README.md)
-- [Slash Commands](../01-slash-commands/)
-- [Memory](../02-memory/)
-- [Skills](../03-skills/)
-- [Subagents](../04-subagents/)
-- [MCP](../05-mcp/)
-- [Hooks](../06-hooks/)
-- [Plugins](../07-plugins/)
-- [Checkpoints](../08-checkpoints/)
-- [Claude Documentation](https://docs.claude.com)
-- [MCP GitHub Servers](https://github.com/modelcontextprotocol/servers)
+- [Official Interactive Mode Documentation](https://code.claude.com/docs/en/interactive-mode)
+- [Official Headless Mode Documentation](https://code.claude.com/docs/en/headless)
+- [CLI Reference](https://code.claude.com/docs/en/cli-reference)
+- [Checkpoints Guide](../08-checkpoints/) - Session management and rewinding
+- [Slash Commands](../01-slash-commands/) - Command reference
+- [Memory Guide](../02-memory/) - Persistent context
+- [Skills Guide](../03-skills/) - Autonomous capabilities
+- [Subagents Guide](../04-subagents/) - Delegated task execution
+- [MCP Guide](../05-mcp/) - External data access
+- [Hooks Guide](../06-hooks/) - Event-driven automation
+- [Plugins Guide](../07-plugins/) - Bundled extensions

10-cli/README.md

@@ -121,6 +121,16 @@ claude --append-system-prompt "Always include unit tests with code examples"
 claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py"
 ```
 
+### System Prompt Flags Comparison
+
+| Flag | Behavior | Interactive | Print |
+|------|----------|-------------|-------|
+| `--system-prompt` | Replaces entire default system prompt | ✅ | ✅ |
+| `--system-prompt-file` | Replaces with prompt from file | ❌ | ✅ |
+| `--append-system-prompt` | Appends to default system prompt | ✅ | ✅ |
+
+**Use `--system-prompt-file` only in print mode. For interactive mode, use `--system-prompt` or `--append-system-prompt`.**
+
 ## Tool & Permission Management
 
 | Flag | Description | Example |
@@ -233,6 +243,26 @@ claude --resume feature-auth --fork-session "try alternative approach"
 claude --session-id "550e8400-e29b-41d4-a716-446655440000" "continue"
 ```
 
+### Session Fork
+
+Create a branch from an existing session for experimentation:
+
+```bash
+# Fork a session to try a different approach
+claude --resume abc123 --fork-session "try alternative implementation"
+
+# Fork with a custom message
+claude -r "feature-auth" --fork-session "test with different architecture"
+```
+
+**Use Cases:**
+- Try alternative implementations without losing the original session
+- Experiment with different approaches in parallel
+- Create branches from successful work for variations
+- Test breaking changes without affecting the main session
+
+The original session remains unchanged, and the fork becomes a new independent session.
+
 ## Advanced Features
 
 | Flag | Description | Example |
@@ -244,6 +274,7 @@ claude --session-id "550e8400-e29b-41d4-a716-446655440000" "continue"
 | `--debug` | Enable debug mode with filtering | `claude --debug "api,mcp"` |
 | `--enable-lsp-logging` | Enable verbose LSP logging | `claude --enable-lsp-logging` |
 | `--betas` | Beta headers for API requests | `claude --betas interleaved-thinking` |
+| `--plugin-dir` | Load plugins from directory (repeatable) | `claude --plugin-dir ./my-plugin` |
 
 ### Advanced Examples
 
@@ -260,7 +291,31 @@ claude --ide "help me with this file"
 
 ## Agents Configuration
 
-The `--agents` flag accepts a JSON object defining custom subagents:
+The `--agents` flag accepts a JSON object defining custom subagents for a session.
+
+### Agents JSON Format
+
+```json
+{
+  "agent-name": {
+    "description": "Required: when to invoke this agent",
+    "prompt": "Required: system prompt for the agent",
+    "tools": ["Optional", "array", "of", "tools"],
+    "model": "optional: sonnet|opus|haiku"
+  }
+}
+```
+
+**Required Fields:**
+- `description` - Natural language description of when to use this agent
+- `prompt` - System prompt that defines the agent's role and behavior
+
+**Optional Fields:**
+- `tools` - Array of available tools (inherits all if omitted)
+  - Format: `["Read", "Grep", "Glob", "Bash"]`
+- `model` - Model to use: `sonnet`, `opus`, or `haiku`
+
+### Complete Agents Example
 
 ```json
 {
@@ -272,18 +327,20 @@ The `--agents` flag accepts a JSON object defining custom subagents:
   },
   "debugger": {
     "description": "Debugging specialist for errors and test failures.",
-    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
+    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.",
+    "tools": ["Read", "Edit", "Bash", "Grep"],
+    "model": "opus"
+  },
+  "documenter": {
+    "description": "Documentation specialist for generating guides.",
+    "prompt": "You are a technical writer. Create clear, comprehensive documentation.",
+    "tools": ["Read", "Write"],
+    "model": "haiku"
   }
 }
 ```
 
-**Fields:**
-- `description` (required): When to invoke the subagent
-- `prompt` (required): System prompt for the subagent
-- `tools` (optional): Specific tools available (inherits all if omitted)
-- `model` (optional): sonnet, opus, or haiku (uses default if omitted)
-
-### Agents Example
+### Agents Command Examples
 
 ```bash
 # Define custom agents inline
@@ -295,8 +352,23 @@ claude --agents '{
     "model": "opus"
   }
 }' "audit this codebase for security issues"
+
+# Load agents from file
+claude --agents "$(cat ~/.claude/agents.json)" "review the auth module"
+
+# Combine with other flags
+claude -p --agents "$(cat agents.json)" --model sonnet "analyze performance"
 ```
 
+### Agent Priority
+
+When multiple agent definitions exist, they are loaded in this priority order:
+1. **CLI-defined** (`--agents` flag) - Session-specific
+2. **User-level** (`~/.claude/agents/`) - All projects
+3. **Project-level** (`.claude/agents/`) - Current project
+
+CLI-defined agents override both user and project agents for the session.
+
 ---
 
 ## High-Value Use Cases
@@ -485,7 +557,7 @@ claude -p --max-turns 2 \
 
 ### 7. JSON API Integration
 
-Use Claude as a programmable API for your tools.
+Use Claude as a programmable API for your tools with `jq` parsing.
 
 ```bash
 # Get structured analysis
@@ -504,6 +576,36 @@ if echo "$RESULT" | jq -e '.secure == false' > /dev/null; then
 fi
 ```
 
+### jq Parsing Examples
+
+Parse and process Claude's JSON output using `jq`:
+
+```bash
+# Extract specific fields
+claude -p --output-format json "analyze this code" | jq '.result'
+
+# Filter array elements
+claude -p --output-format json "list issues" | jq -r '.issues[] | select(.severity=="high")'
+
+# Extract multiple fields
+claude -p --output-format json "describe the project" | jq -r '.{name, version, description}'
+
+# Convert to CSV
+claude -p --output-format json "list functions" | jq -r '.functions[] | [.name, .lineCount] | @csv'
+
+# Conditional processing
+claude -p --output-format json "check security" | jq 'if .vulnerabilities | length > 0 then "UNSAFE" else "SAFE" end'
+
+# Extract nested values
+claude -p --output-format json "analyze performance" | jq '.metrics.cpu.usage'
+
+# Process entire array
+claude -p --output-format json "find todos" | jq '.todos | length'
+
+# Transform output
+claude -p --output-format json "list improvements" | jq 'map({title: .title, priority: .priority})'
+```
+
 ---
 
 ## Quick Reference
@@ -589,13 +691,15 @@ claude -p --output-format json "query"
 
 ---
 
-## Related Concepts
+## Additional Resources
 
+- **[Official CLI Reference](https://code.claude.com/docs/en/cli-reference)** - Complete command reference
+- **[Headless Mode Documentation](https://code.claude.com/docs/en/headless)** - Automated execution
 - **[Slash Commands](../01-slash-commands/)** - Custom shortcuts within Claude
-- **[Memory](../02-memory/)** - Persistent context via CLAUDE.md
+- **[Memory Guide](../02-memory/)** - Persistent context via CLAUDE.md
 - **[MCP Protocol](../05-mcp/)** - External tool integrations
 - **[Advanced Features](../09-advanced-features/)** - Planning mode, extended thinking
-- **[Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)**
+- **[Subagents Guide](../04-subagents/)** - Delegated task execution
 
 ---