├── .clinerules
    ├── c#-guide.md
    ├── cline-architecture.md
    ├── cline-continuous-improvement-protocol.md
    ├── cline-for-research.md
    ├── cline-for-slides.md
    ├── cline-for-webdev-ui.md
    ├── comprehensive-slide-dev-guide.md
    ├── gemini-comprehensive-software-engineering-guide.md
    ├── mcp-development-protocol.md
    ├── memory-bank.md
    ├── new-task-automation
    ├── next-js-supabase.md
    ├── self-improving-cline.md
    ├── sequential-thinking.md
    ├── uv-python-usage-guide.md
    └── writing-effective-clinerules.md
├── README.md
└── workflows
    └── pr-review-cline.md


/.clinerules/cline-architecture.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: Defines Cline's extension architecture, components, data flow, and development guidelines.
  3 | author: https://github.com/cline
  4 | version: 1.0
  5 | tags: ["architecture", "development-guide", "extension", "vscode", "core-behavior"]
  6 | globs: ["*"]
  7 | ---
  8 | # Cline Extension Architecture & Development Guide
  9 | 
 10 | ## Project Overview
 11 | 
 12 | Cline is a VSCode extension that provides AI assistance through a combination of a core extension backend and a React-based webview frontend. The extension is built with TypeScript and follows a modular architecture pattern.
 13 | 
 14 | ## Architecture Overview
 15 | 
 16 | ```mermaid
 17 | graph TB
 18 |     subgraph VSCodeExtensionHost[VSCode Extension Host]
 19 |         subgraph CoreExtension[Core Extension]
 20 |             ExtensionEntry[Extension Entry<br/>src/extension.ts]
 21 |             WebviewProvider[WebviewProvider<br/>src/core/webview/index.ts]
 22 |             Controller[Controller<br/>src/core/controller/index.ts]
 23 |             Task[Task<br/>src/core/task/index.ts]
 24 |             GlobalState[VSCode Global State]
 25 |             SecretsStorage[VSCode Secrets Storage]
 26 |             McpHub[McpHub<br/>src/services/mcp/McpHub.ts]
 27 |         end
 28 | 
 29 |         subgraph WebviewUI[Webview UI]
 30 |             WebviewApp[React App<br/>webview-ui/src/App.tsx]
 31 |             ExtStateContext[ExtensionStateContext<br/>webview-ui/src/context/ExtensionStateContext.tsx]
 32 |             ReactComponents[React Components]
 33 |         end
 34 | 
 35 |         subgraph Storage
 36 |             TaskStorage[Task Storage<br/>Per-Task Files & History]
 37 |             CheckpointSystem[Git-based Checkpoints]
 38 |         end
 39 | 
 40 |         subgraph apiProviders[API Providers]
 41 |             AnthropicAPI[Anthropic]
 42 |             OpenRouterAPI[OpenRouter]
 43 |             BedrockAPI[AWS Bedrock]
 44 |             OtherAPIs[Other Providers]
 45 |         end
 46 | 
 47 |         subgraph MCPServers[MCP Servers]
 48 |             ExternalMcpServers[External MCP Servers]
 49 |         end
 50 |     end
 51 | 
 52 |     %% Core Extension Data Flow
 53 |     ExtensionEntry --> WebviewProvider
 54 |     WebviewProvider --> Controller
 55 |     Controller --> Task
 56 |     Controller --> McpHub
 57 |     Task --> GlobalState
 58 |     Task --> SecretsStorage
 59 |     Task --> TaskStorage
 60 |     Task --> CheckpointSystem
 61 |     Task --> |API Requests| apiProviders
 62 |     McpHub --> |Connects to| ExternalMcpServers
 63 |     Task --> |Uses| McpHub
 64 | 
 65 |     %% Webview Data Flow
 66 |     WebviewApp --> ExtStateContext
 67 |     ExtStateContext --> ReactComponents
 68 | 
 69 |     %% Bidirectional Communication
 70 |     WebviewProvider <-->|postMessage| ExtStateContext
 71 | 
 72 |     style GlobalState fill:#f9f,stroke:#333,stroke-width:2px
 73 |     style SecretsStorage fill:#f9f,stroke:#333,stroke-width:2px
 74 |     style ExtStateContext fill:#bbf,stroke:#333,stroke-width:2px
 75 |     style WebviewProvider fill:#bfb,stroke:#333,stroke-width:2px
 76 |     style McpHub fill:#bfb,stroke:#333,stroke-width:2px
 77 |     style apiProviders fill:#fdb,stroke:#333,stroke-width:2px
 78 | ```
 79 | 
 80 | ## Definitions 
 81 | 
 82 | - **Core Extension**: Anything inside the src folder, organized into modular components
 83 | - **Core Extension State**: Managed by the Controller class in src/core/controller/index.ts, which serves as the single source of truth for the extension's state. It manages multiple types of persistent storage (global state, workspace state, and secrets), handles state distribution to both the core extension and webview components, and coordinates state across multiple extension instances. This includes managing API configurations, task history, settings, and MCP configurations.
 84 | - **Webview**: Anything inside the webview-ui. All the react or view's seen by the user and user interaction components
 85 | - **Webview State**: Managed by ExtensionStateContext in webview-ui/src/context/ExtensionStateContext.tsx, which provides React components with access to the extension's state through a context provider pattern. It maintains local state for UI components, handles real-time updates through message events, manages partial message updates, and provides methods for state modifications. The context includes extension version, messages, task history, theme, API configurations, MCP servers, marketplace catalog, and workspace file paths. It synchronizes with the core extension through VSCode's message passing system and provides type-safe access to state through a custom hook (useExtensionState).
 86 | 
 87 | ### Core Extension Architecture
 88 | 
 89 | The core extension follows a clear hierarchical structure:
 90 | 
 91 | 1. **WebviewProvider** (src/core/webview/index.ts): Manages the webview lifecycle and communication
 92 | 2. **Controller** (src/core/controller/index.ts): Handles webview messages and task management
 93 | 3. **Task** (src/core/task/index.ts): Executes API requests and tool operations
 94 | 
 95 | This architecture provides clear separation of concerns:
 96 | - WebviewProvider focuses on VSCode webview integration
 97 | - Controller manages state and coordinates tasks
 98 | - Task handles the execution of AI requests and tool operations
 99 | 
100 | ### WebviewProvider Implementation
101 | 
102 | The WebviewProvider class in `src/core/webview/index.ts` is responsible for:
103 | 
104 | - Managing multiple active instances through a static set (`activeInstances`)
105 | - Handling webview lifecycle events (creation, visibility changes, disposal)
106 | - Implementing HTML content generation with proper CSP headers
107 | - Supporting Hot Module Replacement (HMR) for development
108 | - Setting up message listeners between the webview and extension
109 | 
110 | The WebviewProvider maintains a reference to the Controller and delegates message handling to it. It also handles the creation of both sidebar and tab panel webviews, allowing Cline to be used in different contexts within VSCode.
111 | 
112 | ### Core Extension State
113 | 
114 | The `Controller` class manages multiple types of persistent storage:
115 | 
116 | - **Global State:** Stored across all VSCode instances. Used for settings and data that should persist globally.
117 | - **Workspace State:** Specific to the current workspace. Used for task-specific data and settings.
118 | - **Secrets:** Secure storage for sensitive information like API keys.
119 | 
120 | The `Controller` handles the distribution of state to both the core extension and webview components. It also coordinates state across multiple extension instances, ensuring consistency.
121 | 
122 | State synchronization between instances is handled through:
123 | - File-based storage for task history and conversation data
124 | - VSCode's global state API for settings and configuration
125 | - Secrets storage for sensitive information
126 | - Event listeners for file changes and configuration updates
127 | 
128 | The Controller implements methods for:
129 | - Saving and loading task state
130 | - Managing API configurations
131 | - Handling user authentication
132 | - Coordinating MCP server connections
133 | - Managing task history and checkpoints
134 | 
135 | ### Webview State
136 | 
137 | The `ExtensionStateContext` in `webview-ui/src/context/ExtensionStateContext.tsx` provides React components with access to the extension's state. It uses a context provider pattern and maintains local state for UI components. The context includes:
138 | 
139 | - Extension version
140 | - Messages
141 | - Task history
142 | - Theme
143 | - API configurations
144 | - MCP servers
145 | - Marketplace catalog
146 | - Workspace file paths
147 | 
148 | It synchronizes with the core extension through VSCode's message passing system and provides type-safe access to the state via a custom hook (`useExtensionState`).
149 | 
150 | The ExtensionStateContext handles:
151 | - Real-time updates through message events
152 | - Partial message updates for streaming content
153 | - State modifications through setter methods
154 | - Type-safe access to state through a custom hook
155 | 
156 | ## API Provider System
157 | 
158 | Cline supports multiple AI providers through a modular API provider system. Each provider is implemented as a separate module in the `src/api/providers/` directory and follows a common interface.
159 | 
160 | ### API Provider Architecture
161 | 
162 | The API system consists of:
163 | 
164 | 1. **API Handlers**: Provider-specific implementations in `src/api/providers/`
165 | 2. **API Transformers**: Stream transformation utilities in `src/api/transform/`
166 | 3. **API Configuration**: User settings for API keys and endpoints
167 | 4. **API Factory**: Builder function to create the appropriate handler
168 | 
169 | Key providers include:
170 | - **Anthropic**: Direct integration with Claude models
171 | - **OpenRouter**: Meta-provider supporting multiple model providers
172 | - **AWS Bedrock**: Integration with Amazon's AI services
173 | - **Gemini**: Google's AI models
174 | - **Ollama**: Local model hosting
175 | - **LM Studio**: Local model hosting
176 | - **VSCode LM**: VSCode's built-in language models
177 | 
178 | ### API Configuration Management
179 | 
180 | API configurations are stored securely:
181 | - API keys are stored in VSCode's secrets storage
182 | - Model selections and non-sensitive settings are stored in global state
183 | - The Controller manages switching between providers and updating configurations
184 | 
185 | The system supports:
186 | - Secure storage of API keys
187 | - Model selection and configuration
188 | - Automatic retry and error handling
189 | - Token usage tracking and cost calculation
190 | - Context window management
191 | 
192 | ### Plan/Act Mode API Configuration
193 | 
194 | Cline supports separate model configurations for Plan and Act modes:
195 | - Different models can be used for planning vs. execution
196 | - The system preserves model selections when switching modes
197 | - The Controller handles the transition between modes and updates the API configuration accordingly
198 | 
199 | ## Task Execution System
200 | 
201 | The Task class is responsible for executing AI requests and tool operations. Each task runs in its own instance of the Task class, ensuring isolation and proper state management.
202 | 
203 | ### Task Execution Loop
204 | 
205 | The core task execution loop follows this pattern:
206 | 
207 | ```typescript
208 | class Task {
209 |   async initiateTaskLoop(userContent: UserContent, isNewTask: boolean) {
210 |     while (!this.abort) {
211 |       // 1. Make API request and stream response
212 |       const stream = this.attemptApiRequest()
213 |       
214 |       // 2. Parse and present content blocks
215 |       for await (const chunk of stream) {
216 |         switch (chunk.type) {
217 |           case "text":
218 |             // Parse into content blocks
219 |             this.assistantMessageContent = parseAssistantMessage(chunk.text)
220 |             // Present blocks to user
221 |             await this.presentAssistantMessage()
222 |             break
223 |         }
224 |       }
225 |       
226 |       // 3. Wait for tool execution to complete
227 |       await pWaitFor(() => this.userMessageContentReady)
228 |       
229 |       // 4. Continue loop with tool result
230 |       const recDidEndLoop = await this.recursivelyMakeClineRequests(
231 |         this.userMessageContent
232 |       )
233 |     }
234 |   }
235 | }
236 | ```
237 | 
238 | ### Message Streaming System
239 | 
240 | The streaming system handles real-time updates and partial content:
241 | 
242 | ```typescript
243 | class Task {
244 |   async presentAssistantMessage() {
245 |     // Handle streaming locks to prevent race conditions
246 |     if (this.presentAssistantMessageLocked) {
247 |       this.presentAssistantMessageHasPendingUpdates = true
248 |       return
249 |     }
250 |     this.presentAssistantMessageLocked = true
251 | 
252 |     // Present current content block
253 |     const block = this.assistantMessageContent[this.currentStreamingContentIndex]
254 |     
255 |     // Handle different types of content
256 |     switch (block.type) {
257 |       case "text":
258 |         await this.say("text", content, undefined, block.partial)
259 |         break
260 |       case "tool_use":
261 |         // Handle tool execution
262 |         break
263 |     }
264 | 
265 |     // Move to next block if complete
266 |     if (!block.partial) {
267 |       this.currentStreamingContentIndex++
268 |     }
269 |   }
270 | }
271 | ```
272 | 
273 | ### Tool Execution Flow
274 | 
275 | Tools follow a strict execution pattern:
276 | 
277 | ```typescript
278 | class Task {
279 |   async executeToolWithApproval(block: ToolBlock) {
280 |     // 1. Check auto-approval settings
281 |     if (this.shouldAutoApproveTool(block.name)) {
282 |       await this.say("tool", message)
283 |       this.consecutiveAutoApprovedRequestsCount++
284 |     } else {
285 |       // 2. Request user approval
286 |       const didApprove = await askApproval("tool", message)
287 |       if (!didApprove) {
288 |         this.didRejectTool = true
289 |         return
290 |       }
291 |     }
292 | 
293 |     // 3. Execute tool
294 |     const result = await this.executeTool(block)
295 | 
296 |     // 4. Save checkpoint
297 |     await this.saveCheckpoint()
298 | 
299 |     // 5. Return result to API
300 |     return result
301 |   }
302 | }
303 | ```
304 | 
305 | ### Error Handling & Recovery
306 | 
307 | The system includes robust error handling:
308 | 
309 | ```typescript
310 | class Task {
311 |   async handleError(action: string, error: Error) {
312 |     // 1. Check if task was abandoned
313 |     if (this.abandoned) return
314 |     
315 |     // 2. Format error message
316 |     const errorString = `Error ${action}: ${error.message}`
317 |     
318 |     // 3. Present error to user
319 |     await this.say("error", errorString)
320 |     
321 |     // 4. Add error to tool results
322 |     pushToolResult(formatResponse.toolError(errorString))
323 |     
324 |     // 5. Cleanup resources
325 |     await this.diffViewProvider.revertChanges()
326 |     await this.browserSession.closeBrowser()
327 |   }
328 | }
329 | ```
330 | 
331 | ### API Request & Token Management
332 | 
333 | The Task class handles API requests with built-in retry, streaming, and token management:
334 | 
335 | ```typescript
336 | class Task {
337 |   async *attemptApiRequest(previousApiReqIndex: number): ApiStream {
338 |     // 1. Wait for MCP servers to connect
339 |     await pWaitFor(() => this.controllerRef.deref()?.mcpHub?.isConnecting !== true)
340 | 
341 |     // 2. Manage context window
342 |     const previousRequest = this.clineMessages[previousApiReqIndex]
343 |     if (previousRequest?.text) {
344 |       const { tokensIn, tokensOut } = JSON.parse(previousRequest.text || "{}")
345 |       const totalTokens = (tokensIn || 0) + (tokensOut || 0)
346 |       
347 |       // Truncate conversation if approaching context limit
348 |       if (totalTokens >= maxAllowedSize) {
349 |         this.conversationHistoryDeletedRange = this.contextManager.getNextTruncationRange(
350 |           this.apiConversationHistory,
351 |           this.conversationHistoryDeletedRange,
352 |           totalTokens / 2 > maxAllowedSize ? "quarter" : "half"
353 |         )
354 |       }
355 |     }
356 | 
357 |     // 3. Handle streaming with automatic retry
358 |     try {
359 |       this.isWaitingForFirstChunk = true
360 |       const firstChunk = await iterator.next()
361 |       yield firstChunk.value
362 |       this.isWaitingForFirstChunk = false
363 |       
364 |       // Stream remaining chunks
365 |       yield* iterator
366 |     } catch (error) {
367 |       // 4. Error handling with retry
368 |       if (isOpenRouter && !this.didAutomaticallyRetryFailedApiRequest) {
369 |         await setTimeoutPromise(1000)
370 |         this.didAutomaticallyRetryFailedApiRequest = true
371 |         yield* this.attemptApiRequest(previousApiReqIndex)
372 |         return
373 |       }
374 |       
375 |       // 5. Ask user to retry if automatic retry failed
376 |       const { response } = await this.ask(
377 |         "api_req_failed",
378 |         this.formatErrorWithStatusCode(error)
379 |       )
380 |       if (response === "yesButtonClicked") {
381 |         await this.say("api_req_retried")
382 |         yield* this.attemptApiRequest(previousApiReqIndex)
383 |         return
384 |       }
385 |     }
386 |   }
387 | }
388 | ```
389 | 
390 | Key features:
391 | 
392 | 1. **Context Window Management**
393 |    - Tracks token usage across requests
394 |    - Automatically truncates conversation when needed
395 |    - Preserves important context while freeing space
396 |    - Handles different model context sizes
397 | 
398 | 2. **Streaming Architecture**
399 |    - Real-time chunk processing
400 |    - Partial content handling
401 |    - Race condition prevention
402 |    - Error recovery during streaming
403 | 
404 | 3. **Error Handling**
405 |    - Automatic retry for transient failures
406 |    - User-prompted retry for persistent issues
407 |    - Detailed error reporting
408 |    - State cleanup on failure
409 | 
410 | 4. **Token Tracking**
411 |    - Per-request token counting
412 |    - Cumulative usage tracking
413 |    - Cost calculation
414 |    - Cache hit monitoring
415 | 
416 | ### Context Management System
417 | 
418 | The Context Management System handles conversation history truncation to prevent context window overflow errors. Implemented in the `ContextManager` class, it ensures long-running conversations remain within model context limits while preserving critical context.
419 | 
420 | Key features:
421 | 
422 | 1. **Model-Aware Sizing**: Dynamically adjusts based on different model context windows (64K for DeepSeek, 128K for most models, 200K for Claude).
423 | 
424 | 2. **Proactive Truncation**: Monitors token usage and preemptively truncates conversations when approaching limits, maintaining buffers of 27K-40K tokens depending on the model.
425 | 
426 | 3. **Intelligent Preservation**: Always preserves the original task message and maintains the user-assistant conversation structure when truncating.
427 | 
428 | 4. **Adaptive Strategies**: Uses different truncation strategies based on context pressure - removing half of the conversation for moderate pressure or three-quarters for severe pressure.
429 | 
430 | 5. **Error Recovery**: Includes specialized detection for context window errors from different providers with automatic retry and more aggressive truncation when needed.
431 | 
432 | ### Task State & Resumption
433 | 
434 | The Task class provides robust task state management and resumption capabilities:
435 | 
436 | ```typescript
437 | class Task {
438 |   async resumeTaskFromHistory() {
439 |     // 1. Load saved state
440 |     this.clineMessages = await getSavedClineMessages(this.getContext(), this.taskId)
441 |     this.apiConversationHistory = await getSavedApiConversationHistory(this.getContext(), this.taskId)
442 | 
443 |     // 2. Handle interrupted tool executions
444 |     const lastMessage = this.apiConversationHistory[this.apiConversationHistory.length - 1]
445 |     if (lastMessage.role === "assistant") {
446 |       const toolUseBlocks = content.filter(block => block.type === "tool_use")
447 |       if (toolUseBlocks.length > 0) {
448 |         // Add interrupted tool responses
449 |         const toolResponses = toolUseBlocks.map(block => ({
450 |           type: "tool_result",
451 |           tool_use_id: block.id,
452 |           content: "Task was interrupted before this tool call could be completed."
453 |         }))
454 |         modifiedOldUserContent = [...toolResponses]
455 |       }
456 |     }
457 | 
458 |     // 3. Notify about interruption
459 |     const agoText = this.getTimeAgoText(lastMessage?.ts)
460 |     newUserContent.push({
461 |       type: "text",
462 |       text: `[TASK RESUMPTION] This task was interrupted ${agoText}. It may or may not be complete, so please reassess the task context.`
463 |     })
464 | 
465 |     // 4. Resume task execution
466 |     await this.initiateTaskLoop(newUserContent, false)
467 |   }
468 | 
469 |   private async saveTaskState() {
470 |     // Save conversation history
471 |     await saveApiConversationHistory(this.getContext(), this.taskId, this.apiConversationHistory)
472 |     await saveClineMessages(this.getContext(), this.taskId, this.clineMessages)
473 |     
474 |     // Create checkpoint
475 |     const commitHash = await this.checkpointTracker?.commit()
476 |     
477 |     // Update task history
478 |     await this.controllerRef.deref()?.updateTaskHistory({
479 |       id: this.taskId,
480 |       ts: lastMessage.ts,
481 |       task: taskMessage.text,
482 |       // ... other metadata
483 |     })
484 |   }
485 | }
486 | ```
487 | 
488 | Key aspects of task state management:
489 | 
490 | 1. **Task Persistence**
491 |    - Each task has a unique ID and dedicated storage directory
492 |    - Conversation history is saved after each message
493 |    - File changes are tracked through Git-based checkpoints
494 |    - Terminal output and browser state are preserved
495 | 
496 | 2. **State Recovery**
497 |    - Tasks can be resumed from any point
498 |    - Interrupted tool executions are handled gracefully
499 |    - File changes can be restored from checkpoints
500 |    - Context is preserved across VSCode sessions
501 | 
502 | 3. **Workspace Synchronization**
503 |    - File changes are tracked through Git
504 |    - Checkpoints are created after tool executions
505 |    - State can be restored to any checkpoint
506 |    - Changes can be compared between checkpoints
507 | 
508 | 4. **Error Recovery**
509 |    - Failed API requests can be retried
510 |    - Interrupted tool executions are marked
511 |    - Resources are cleaned up properly
512 |    - User is notified of state changes
513 | 
514 | ## Plan/Act Mode System
515 | 
516 | Cline implements a dual-mode system that separates planning from execution:
517 | 
518 | ### Mode Architecture
519 | 
520 | The Plan/Act mode system consists of:
521 | 
522 | 1. **Mode State**: Stored in `chatSettings.mode` in the Controller's state
523 | 2. **Mode Switching**: Handled by `togglePlanActModeWithChatSettings` in the Controller
524 | 3. **Mode-specific Models**: Optional configuration to use different models for each mode
525 | 4. **Mode-specific Prompting**: Different system prompts for planning vs. execution
526 | 
527 | ### Mode Switching Process
528 | 
529 | When switching between modes:
530 | 
531 | 1. The current model configuration is saved to mode-specific state
532 | 2. The previous mode's model configuration is restored
533 | 3. The Task instance is updated with the new mode
534 | 4. The webview is notified of the mode change
535 | 5. Telemetry events are captured for analytics
536 | 
537 | ### Plan Mode
538 | 
539 | Plan mode is designed for:
540 | - Information gathering and context building
541 | - Asking clarifying questions
542 | - Creating detailed execution plans
543 | - Discussing approaches with the user
544 | 
545 | In Plan mode, the AI uses the `plan_mode_respond` tool to engage in conversational planning without executing actions.
546 | 
547 | ### Act Mode
548 | 
549 | Act mode is designed for:
550 | - Executing the planned actions
551 | - Using tools to modify files, run commands, etc.
552 | - Implementing the solution
553 | - Providing results and completion feedback
554 | 
555 | In Act mode, the AI has access to all tools except `plan_mode_respond` and focuses on implementation rather than discussion.
556 | 
557 | ## Data Flow & State Management
558 | 
559 | ### Core Extension Role
560 | 
561 | The Controller acts as the single source of truth for all persistent state. It:
562 | - Manages VSCode global state and secrets storage
563 | - Coordinates state updates between components
564 | - Ensures state consistency across webview reloads
565 | - Handles task-specific state persistence
566 | - Manages checkpoint creation and restoration
567 | 
568 | ### Terminal Management
569 | 
570 | The Task class manages terminal instances and command execution:
571 | 
572 | ```typescript
573 | class Task {
574 |   async executeCommandTool(command: string): Promise<[boolean, ToolResponse]> {
575 |     // 1. Get or create terminal
576 |     const terminalInfo = await this.terminalManager.getOrCreateTerminal(cwd)
577 |     terminalInfo.terminal.show()
578 | 
579 |     // 2. Execute command with output streaming
580 |     const process = this.terminalManager.runCommand(terminalInfo, command)
581 |     
582 |     // 3. Handle real-time output
583 |     let result = ""
584 |     process.on("line", (line) => {
585 |       result += line + "\n"
586 |       if (!didContinue) {
587 |         sendCommandOutput(line)
588 |       } else {
589 |         this.say("command_output", line)
590 |       }
591 |     })
592 | 
593 |     // 4. Wait for completion or user feedback
594 |     let completed = false
595 |     process.once("completed", () => {
596 |       completed = true
597 |     })
598 | 
599 |     await process
600 | 
601 |     // 5. Return result
602 |     if (completed) {
603 |       return [false, `Command executed.\n${result}`]
604 |     } else {
605 |       return [
606 |         false,
607 |         `Command is still running in the user's terminal.\n${result}\n\nYou will be updated on the terminal status and new output in the future.`
608 |       ]
609 |     }
610 |   }
611 | }
612 | ```
613 | 
614 | Key features:
615 | 1. **Terminal Instance Management**
616 |    - Multiple terminal support
617 |    - Terminal state tracking (busy/inactive)
618 |    - Process cooldown monitoring
619 |    - Output history per terminal
620 | 
621 | 2. **Command Execution**
622 |    - Real-time output streaming
623 |    - User feedback handling
624 |    - Process state monitoring
625 |    - Error recovery
626 | 
627 | ### Browser Session Management
628 | 
629 | The Task class handles browser automation through Puppeteer:
630 | 
631 | ```typescript
632 | class Task {
633 |   async executeBrowserAction(action: BrowserAction): Promise<BrowserActionResult> {
634 |     switch (action) {
635 |       case "launch":
636 |         // 1. Launch browser with fixed resolution
637 |         await this.browserSession.launchBrowser()
638 |         return await this.browserSession.navigateToUrl(url)
639 | 
640 |       case "click":
641 |         // 2. Handle click actions with coordinates
642 |         return await this.browserSession.click(coordinate)
643 | 
644 |       case "type":
645 |         // 3. Handle keyboard input
646 |         return await this.browserSession.type(text)
647 | 
648 |       case "close":
649 |         // 4. Clean up resources
650 |         return await this.browserSession.closeBrowser()
651 |     }
652 |   }
653 | }
654 | ```
655 | 
656 | Key aspects:
657 | 1. **Browser Control**
658 |    - Fixed 900x600 resolution window
659 |    - Single instance per task lifecycle
660 |    - Automatic cleanup on task completion
661 |    - Console log capture
662 | 
663 | 2. **Interaction Handling**
664 |    - Coordinate-based clicking
665 |    - Keyboard input simulation
666 |    - Screenshot capture
667 |    - Error recovery
668 | 
669 | ## MCP (Model Context Protocol) Integration
670 | 
671 | ### MCP Architecture
672 | 
673 | The MCP system consists of:
674 | 
675 | 1. **McpHub Class**: Central manager in `src/services/mcp/McpHub.ts`
676 | 2. **MCP Connections**: Manages connections to external MCP servers
677 | 3. **MCP Settings**: Configuration stored in a JSON file
678 | 4. **MCP Marketplace**: Online catalog of available MCP servers
679 | 5. **MCP Tools & Resources**: Capabilities exposed by connected servers
680 | 
681 | The McpHub class:
682 | - Manages the lifecycle of MCP server connections
683 | - Handles server configuration through a settings file
684 | - Provides methods for calling tools and accessing resources
685 | - Implements auto-approval settings for MCP tools
686 | - Monitors server health and handles reconnection
687 | 
688 | ### MCP Server Types
689 | 
690 | Cline supports two types of MCP server connections:
691 | - **Stdio**: Command-line based servers that communicate via standard I/O
692 | - **SSE**: HTTP-based servers that communicate via Server-Sent Events
693 | 
694 | ### MCP Server Management
695 | 
696 | The McpHub class provides methods for:
697 | - Discovering and connecting to MCP servers
698 | - Monitoring server health and status
699 | - Restarting servers when needed
700 | - Managing server configurations
701 | - Setting timeouts and auto-approval rules
702 | 
703 | ### MCP Tool Integration
704 | 
705 | MCP tools are integrated into the Task execution system:
706 | - Tools are discovered and registered at connection time
707 | - The Task class can call MCP tools through the McpHub
708 | - Tool results are streamed back to the AI
709 | - Auto-approval settings can be configured per tool
710 | 
711 | ### MCP Marketplace
712 | 
713 | The MCP Marketplace provides:
714 | - A catalog of available MCP servers
715 | - One-click installation
716 | - README previews
717 | - Server status monitoring
718 | 
719 | The Controller class manages MCP servers through the McpHub service:
720 | 
721 | ```typescript
722 | class Controller {
723 |   mcpHub?: McpHub
724 | 
725 |   constructor(context: vscode.ExtensionContext, outputChannel: vscode.OutputChannel, webviewProvider: WebviewProvider) {
726 |     this.mcpHub = new McpHub(this)
727 |   }
728 | 
729 |   async downloadMcp(mcpId: string) {
730 |     // Fetch server details from marketplace
731 |     const response = await axios.post<McpDownloadResponse>(
732 |       "https://api.cline.bot/v1/mcp/download",
733 |       { mcpId },
734 |       {
735 |         headers: { "Content-Type": "application/json" },
736 |         timeout: 10000,
737 |       }
738 |     )
739 | 
740 |     // Create task with context from README
741 |     const task = `Set up the MCP server from ${mcpDetails.githubUrl}...`
742 | 
743 |     // Initialize task and show chat view
744 |     await this.initClineWithTask(task)
745 |   }
746 | }
747 | ```
748 | 
749 | ## Conclusion
750 | 
751 | This guide provides a comprehensive overview of the Cline extension architecture, with special focus on state management, data persistence, and code organization. Following these patterns ensures robust feature implementation with proper state handling across the extension's components.
752 | 
753 | Remember:
754 | - Always persist important state in the extension
755 | - The core extension follows a WebviewProvider -> Controller -> Task flow
756 | - Use proper typing for all state and messages
757 | - Handle errors and edge cases
758 | - Test state persistence across webview reloads
759 | - Follow the established patterns for consistency
760 | - Place new code in appropriate directories
761 | - Maintain clear separation of concerns
762 | - Install dependencies in correct package.json
763 | 
764 | ## Contributing
765 | 
766 | Contributions to the Cline extension are welcome! Please follow these guidelines:
767 | 
768 | When adding new tools or API providers, follow the existing patterns in the `src/integrations/` and `src/api/providers/` directories, respectively. Ensure that your code is well-documented and includes appropriate error handling.
769 | 
770 | The `.clineignore` file allows users to specify files and directories that Cline should not access. When implementing new features, respect the `.clineignore` rules and ensure that your code does not attempt to read or modify ignored files.
771 | 


--------------------------------------------------------------------------------
/.clinerules/cline-continuous-improvement-protocol.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: Defines Cline's mandatory protocol for self-reflection, persistent knowledge capture using dedicated logs, and continuous improvement of its operational knowledge before task completion.
  3 | author: https://github.com/jeanibarz
  4 | version: 1.0
  5 | tags: ["protocol", "meta", "learning", "reflection", "knowledge-management", "core-behavior"]
  6 | globs: ["*"] # This core protocol is always active and applies to all Cline operations.
  7 | ---
  8 | # Cline Continuous Improvement Protocol
  9 | 
 10 | **Objective:** Ensure Cline proactively learns from tasks, captures knowledge in a structured way, **distills fundamental insights,** refines understanding, and improves efficiency and reliability. This protocol maintains two key files: `memory-bank/raw_reflection_log.md` for initial detailed logging, and `memory-bank/consolidated_learnings.md` for pruned, actionable, long-term knowledge. This is vital for optimal performance and avoiding redundant effort.
 11 | 
 12 | **Core Principle:** Continuous learning and adaptation are **mandatory**. This protocol **must be executed before `attempt_completion`** for tasks with new learning, problem-solving, user feedback, or multiple steps. Trivial mechanical tasks *may* be exempt per higher-level rules; otherwise, execution is default.
 13 | 
 14 | **Key Knowledge Files:**
 15 | *   **`memory-bank/raw_reflection_log.md`**: Contains detailed, timestamped, and task-referenced raw entries from the "Task Review & Analysis" phase. This is the initial dump of all observations.
 16 | *   **`memory-bank/consolidated_learnings.md`**: Contains curated, summarized, and actionable insights derived from `raw_reflection_log.md`. This is the primary, refined knowledge base for long-term use. It should be kept concise and highly relevant.
 17 | 
 18 | ---
 19 | 
 20 | ## 1. Mandatory Pre-Completion Reflection & Raw Knowledge Capture
 21 | 
 22 | Before signaling task completion (e.g., via `attempt_completion`), Cline **must** perform the following internal steps:
 23 | 
 24 | ### 1.1. Task Review & Analysis:
 25 | * Review the completed task (conversation, logs, artifacts).
 26 | * **Identify Learnings:** What new information, techniques, **underlying patterns,** API behaviors, project-specific commands (e.g., test, build, run flags), environment variables, setup quirks, or successful outcomes were discovered? **What core principles can be extracted?**
 27 | * **Identify Difficulties & Mistakes (as Learning Opportunities):** What challenges were faced? Were there any errors, misunderstandings, or inefficiencies? **How can these experiences refine future approaches (resilience & adaptation)?** Did user feedback indicate a misstep?
 28 | * **Identify Successes:** What went particularly well? What strategies or tools were notably effective? **What were the key contributing factors?**
 29 | 
 30 | ### 1.2. Logging to `memory-bank/raw_reflection_log.md`:
 31 | * Based on Task Review & Analysis (1.1), create a timestamped, task-referenced entry in `memory-bank/raw_reflection_log.md` detailing all learnings, difficulties (and their resolutions/learnings), and successes (and contributing factors).
 32 | * This file serves as the initial, detailed record. Its entries are candidates for later consolidation.
 33 | * *Example Entry in `memory-bank/raw_reflection_log.md`:*
 34 |     ```markdown
 35 |     ---
 36 |     Date: {{CURRENT_DATE_YYYY_MM_DD}}
 37 |     TaskRef: "Implement JWT refresh logic for Project Alpha"
 38 | 
 39 |     Learnings:
 40 |     - Discovered `jose` library's `createRemoteJWKSet` is highly effective for dynamic key fetching for Project Alpha's auth.
 41 |     - Confirmed that a 401 error with `X-Reason: token-signature-invalid` from the auth provider requires re-fetching JWKS.
 42 |     - Project Alpha's integration tests: `cd services/auth && poetry run pytest -m integration --maxfail=1`
 43 |     - Required ENV for local testing of Project Alpha auth: `AUTH_API_KEY="test_key_alpha"`
 44 | 
 45 |     Difficulties:
 46 |     - Initial confusion about JWKS caching led to intermittent validation failures. Resolved by implementing a 5-minute cache.
 47 | 
 48 |     Successes:
 49 |     - The 5-minute JWKS cache with explicit bust mechanism proved effective.
 50 | 
 51 |     Improvements_Identified_For_Consolidation:
 52 |     - General pattern: JWKS caching strategy (5-min cache, explicit bust).
 53 |     - Project Alpha: Specific commands and ENV vars.
 54 |     ---
 55 |     ```
 56 | 
 57 | ---
 58 | 
 59 | ## 2. Knowledge Consolidation & Refinement Process (Periodic)
 60 | 
 61 | This outlines refining knowledge from `memory-bank/raw_reflection_log.md` into `memory-bank/consolidated_learnings.md`. This occurs periodically or when `raw_reflection_log.md` grows significantly, not necessarily after each task.
 62 | 
 63 | ### 2.1. Review and Identify for Consolidation:
 64 | * Periodically, or when prompted by the user or significant new raw entries, review `memory-bank/raw_reflection_log.md`.
 65 | * Identify entries/parts representing durable, actionable, or broadly applicable knowledge (e.g., reusable patterns, critical configurations, effective strategies, resolved errors).
 66 | 
 67 | ### 2.2. Synthesize and Transfer to `memory-bank/consolidated_learnings.md`:
 68 | * For identified insights:
 69 |     * Concisely synthesize, summarize, and **distill into generalizable principles or actionable patterns.**
 70 |     * Add refined knowledge to `memory-bank/consolidated_learnings.md`, organizing logically (by topic, project, tech) for easy retrieval.
 71 |     * Ensure `consolidated_learnings.md` content is actionable, **generalizable,** and non-redundant.
 72 | * *Example Entry in `memory-bank/consolidated_learnings.md` (derived from above raw log example):*
 73 |     ```markdown
 74 |     ## JWT Handling & JWKS
 75 |     **Pattern: JWKS Caching Strategy**
 76 |     - For systems using JWKS for token validation, implement a short-lived cache (e.g., 5 minutes) for fetched JWKS.
 77 |     - Include an explicit cache-bust mechanism if immediate key rotation needs to be handled.
 78 |     - *Rationale:* Balances performance by reducing frequent JWKS re-fetching against timely key updates. Mitigates intermittent validation failures due to stale keys.
 79 | 
 80 |     ## Project Alpha - Specifics
 81 |     **Auth Module:**
 82 |     - **Integration Tests:** `cd services/auth && poetry run pytest -m integration --maxfail=1`
 83 |     - **Local Testing ENV:** `AUTH_API_KEY="test_key_alpha"`
 84 |     ```
 85 | 
 86 | ### 2.3. Prune `memory-bank/raw_reflection_log.md`:
 87 | * **Crucially, once information has been successfully transferred and consolidated into `memory-bank/consolidated_learnings.md`, the corresponding original entries or processed parts **must be removed** from `memory-bank/raw_reflection_log.md`.**
 88 | * This keeps `raw_reflection_log.md` focused on recent, unprocessed reflections and prevents it from growing indefinitely with redundant information.
 89 | 
 90 | ### 2.4. Proposing `.clinerule` Enhancements (Exceptional):
 91 | * The primary focus of this protocol is the maintenance of `raw_reflection_log.md` and `consolidated_learnings.md`.
 92 | * If a significant, broadly applicable insight in `consolidated_learnings.md` strongly suggests modifying *another active `.clinerule`* (e.g., core workflow, tech guidance), Cline MAY propose this change after user confirmation. This is exceptional.
 93 | 
 94 | ---
 95 | 
 96 | ## 3. Guidelines for Knowledge Content
 97 | 
 98 | These guidelines apply to entries in `memory-bank/raw_reflection_log.md` (initial capture) and especially to `memory-bank/consolidated_learnings.md` (refined, long-term knowledge).
 99 | 
100 | * **Prioritize High-Value Insights:** Focus on lessons that significantly impact future performance, **lead to more robust or generalizable understanding,** or detail critical errors and their resolutions, major time-saving discoveries, fundamental shifts in understanding, and essential project-specific configurations.
101 | * **Be Concise & Actionable (especially for `consolidated_learnings.md`):** Information should be clear, to the point, and useful when revisited. What can be *done* differently or leveraged next time?
102 | * **Strive for Clarity and Future Usability:** Document insights in a way that is clear and easily understandable for future review, facilitating effective knowledge retrieval and application (akin to self-explainability).
103 | * **Document Persistently, Refine & Prune Continuously:** Capture raw insights immediately. Systematically refine, consolidate, and prune this knowledge as per Section 2.
104 | * **Organize for Retrieval:** Structure `consolidated_learnings.md` logically. Use clear headings and Markdown formatting.
105 | * **Avoid Low-Utility Information in `consolidated_learnings.md`:** This file should not contain trivial statements. Raw, verbose thoughts belong in `raw_reflection_log.md` before pruning.
106 | * **Support Continuous Improvement:** The ultimate goal is to avoid repeating mistakes, accelerate future tasks, and make Cline's operations more robust and reliable. Frame all knowledge with this in mind.
107 | * **Manage Information Density:** Actively work to keep `consolidated_learnings.md` dense with high-value information and free of outdated or overly verbose content. The pruning of `raw_reflection_log.md` is key to this.
108 | 


--------------------------------------------------------------------------------
/.clinerules/cline-for-research.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | description: Guides the user through a research process using available MCP tools, offering choices for refinement, method, and output.
 3 | author: https://github.com/nickbaumann98
 4 | version: 1.0
 5 | tags: ["research", "mcp", "workflow", "assistant-behavior"]
 6 | globs: ["*"]
 7 | ---
 8 | # Cline for Research Assistant
 9 | 
10 | **Objective:** Guide the user through a research process using available MCP tools, offering choices for refinement, method, and output.
11 | 
12 | **Workflow:**
13 | 
14 | 1.  **Initiation:** This rule activates automatically when it is toggled "on" and the user asks a question that appears to be a research request. It then takes the user's initial question as the starting `research_topic`.
15 | 2.  **Topic Confirmation/Refinement:**
16 |     *   Confirm the inferred topic: "Okay, I can research `research_topic`. Would you like to refine this query first?"
17 |     *   Provide selectable options: ["Yes, help refine", "No, proceed with this topic"]
18 |     *   If "Yes": Engage in a brief dialogue to refine `research_topic`.
19 |     *   If "No": Proceed.
20 | 3.  **Research Method Selection:**
21 |     *   Ask the user: "Which research method should I use?"
22 |     *   Provide options:
23 |         *   "Quick Web Search (Serper MCP)"
24 |         *   "AI-Powered Search (Perplexity MCP)"
25 |         *   "Deep Research (Firecrawl MCP)"
26 |     *   Store the choice as `research_method`.
27 | 4.  **Output Format Selection:**
28 |     *   Ask the user: "How should I deliver the results?"
29 |     *   Provide options:
30 |         *   "Summarize in chat"
31 |         *   "Create a Markdown file"
32 |         *   "Create a raw data file (JSON)"
33 |     *   Store the choice as `output_format`.
34 |     *   If a file format is chosen, ask: "What filename should I use? (e.g., `topic_results.md` or `topic_data.json`)" Store as `output_filename`. Default to `research_results.md` or `research_data.json` if no name is provided.
35 | 5.  **Execution:**
36 |     *   Based on `research_method`:
37 |         *   If "Quick Web Search":
38 |             *   Use `use_mcp_tool` with a placeholder for the Serper MCP `search` tool, passing `research_topic`.
39 |             *   Inform the user: "Executing Quick Web Search via Serper MCP..."
40 |         *   If "AI-Powered Search":
41 |             *   Use `use_mcp_tool` for `github.com/pashpashpash/perplexity-mcp` -> `search` tool, passing `research_topic`.
42 |             *   Inform the user: "Executing AI-Powered Search via Perplexity MCP..."
43 |         *   If "Deep Research":
44 |             *   Use `use_mcp_tool` for `github.com/mendableai/firecrawl-mcp-server` -> `firecrawl_deep_research` tool, passing `research_topic`.
45 |             *   Inform the user: "Executing Deep Research via Firecrawl MCP... (This may take a few minutes)"
46 |     *   Store the raw result as `raw_research_data`.
47 | 6.  **Output Delivery:**
48 |     *   Based on `output_format`:
49 |         *   If "Summarize in chat":
50 |             *   Analyze `raw_research_data` and provide a concise summary in the chat.
51 |         *   If "Create a Markdown file":
52 |             *   Determine filename (use `output_filename` or default).
53 |             *   Format `raw_research_data` into Markdown and use `write_to_file` to save it.
54 |             *   Inform the user: "Research results saved to `<filename>`."
55 |         *   If "Create a raw data file":
56 |             *   Determine filename (use `output_filename` or default).
57 |             *   Use `write_to_file` to save `raw_research_data` (likely JSON).
58 |             *   Inform the user: "Raw research data saved to `<filename>`."
59 | 7.  **Completion:** End the rule execution.
60 | 
61 | ---
62 | **Notes:**
63 | 
64 | *   This rule relies on the user having the Perplexity Firecrawl, and Serper MCP servers connected and running.
65 | *   The "Quick Web Search" option is currently hypothetical and would require a Serper MCP server to be implemented and connected.
66 | *   Error handling (e.g., if an MCP tool fails) is omitted for brevity but should be considered for a production rule.
67 | 


--------------------------------------------------------------------------------
/.clinerules/cline-for-slides.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | description: Provides guidelines and best practices for creating and working with Slidev presentation projects.
 3 | author: https://github.com/nickbaumann98
 4 | version: 1.0
 5 | tags: ["slidev", "slides", "markdown", "vue", "vite", "guide"]
 6 | globs: ["slides.md", "**/slides.md", "*.vue", "layouts/**/*.vue", "components/**/*.vue"]
 7 | ---
 8 | # Slidev Project Instructions
 9 | 
10 | This document provides guidelines for working with Slidev projects. Slidev is a Markdown-based presentation tool powered by Vue and Vite.
11 | 
12 | ## Core Concepts & Structure
13 | 
14 | 1. **Entry Point**: The main presentation content is typically in `http://slides.md`.
15 | 2. **Slide Separation**: Slides are separated by `---` on a new line.
16 | 3. **Frontmatter/Headmatter**:
17 | * YAML blocks at the beginning of the file (`--- ... ---`) configure the deck (headmatter) or individual slides (frontmatter).
18 | * Headmatter (first block) applies globally (e.g., `theme`, `title`, `addons`).
19 | * Frontmatter configures specific slides (e.g., `layout`, `background`, `class`, `transition`, `clicks`).
20 | * **YAML Quoting:** Prefer double quotes (`"..."`) for strings containing single quotes (`'`) to avoid parsing errors (e.g., `title: "My Deck's Title"`).
21 | 4. **Layouts**:
22 | * Define the structure of slides. Specified via `layout:` in frontmatter.
23 | * Default layout for the first slide is `cover`, others are `default`.
24 | * Custom layouts are placed in the `layouts/` directory as `.vue` files. Use `<slot />` for default content and named slots (`<slot name="xxx" />`) for specific sections.
25 | 5. **Components**:
26 | * Vue components can be used directly in Markdown (e.g., `<MyComponent />`).
27 | * Components are auto-imported from:
28 | * Slidev built-ins (`@slidev/client/builtin/`).
29 | * The active theme.
30 | * Installed addons.
31 | * The local `components/` directory.
32 | * Custom components go in the `components/` directory as `.vue` files.
33 | 6. **Styles**:
34 | * [UnoCSS](https://unocss.dev) is built-in for utility-first styling. Apply classes directly in Markdown or components.
35 | * Global styles can be added in the `styles/` directory (e.g., `styles/index.css`).
36 | * Scoped styles for a specific slide can be added using `<style scoped>...</style>` within the slide's Markdown.
37 | 7. **Assets**:
38 | * Static assets (images, videos) can be placed in the `public/` directory and referenced with absolute paths starting with `/` (e.g., `background: /my-image.png`).
39 | * Relative paths (e.g., `./image.png`) work for standard Markdown image syntax (`![alt](./image.png)`) but might break in frontmatter or components after building. Prefer the `public/` directory method for reliability.
40 | 8. **Notes**:
41 | * Presenter notes are added as HTML comments (`<!-- ... -->`) at the *very end* of a slide's Markdown content.
42 | * Notes support Markdown formatting.
43 | 
44 | ## Key Features & Syntax
45 | 
46 | 1. **Code Blocks**:
47 | * Use standard Markdown fenced code blocks (e.g., ` ```ts ... ``` `).
48 | * Syntax highlighting is provided by Shiki.
49 | * Supports line highlighting (`{1,3-5}`), line numbers (`{lines:true}`), Monaco editor (`{monaco}`), diffs (`{monaco-diff}`), code imports (`<<< @/path/to/file.js#region {lines=...}`). Refer to the Syntax Guide for details.
50 | 2. **Animations (Clicks)**:
51 | * Use `<v-click>` component or `v-click` directive to reveal elements step-by-step.
52 | * `v-after` reveals elements simultaneously with the previous `v-click`.
53 | * `.hide` modifier (e.g., `v-click.hide`) hides elements instead of showing them.
54 | * `<v-clicks>` component applies `v-click` to its children (useful for lists).
55 | * Control timing with `at="..."` (e.g., `v-click="3"` for absolute click 3, `v-click="'+2'"` for 2 clicks after the previous relative element).
56 | * Specify enter/leave ranges: `v-click="[2, 5]"` (visible from click 2 up to, but not including, 5).
57 | * Override total clicks per slide with `clicks: N` in frontmatter.
58 | 3. **Motion (VueUse Motion)**:
59 | * Use the `v-motion` directive for element transitions (e.g., `:initial="{ x: -80 }" :enter="{ x: 0 }"`).
60 | * Can be triggered by clicks using `:click-N` attributes (e.g., `:click-1="{ y: 30 }"`).
61 | 4. **Slide Transitions**:
62 | * Set in headmatter (`transition: slide-left`) for global effect or frontmatter for specific slides.
63 | * Built-in transitions: `fade`, `fade-out`, `slide-left`, `slide-right`, `slide-up`, `slide-down`, `view-transition`.
64 | * Specify different forward/backward transitions: `transition: slide-left | slide-right`.
65 | 5. **Diagrams**: Supports Mermaid (` ```mermaid ... ``` `) and PlantUML (` ```plantuml ... ``` `).
66 | 6. **LaTeX**: Use `$` for inline math (`$a^2+b^2=c^2$`) and `$$` for block math.
67 | 7. **Global Context**: Access runtime info like `$nav` (navigation controls), `$clicks` (current click count), `$page` (current slide number), `$frontmatter`, `$slidev.configs` within components or directly in Markdown using `{{ }}`. Use composables like `useNav()` from `@slidev/client` in `<script setup>`.
68 | 
69 | ## Development Workflow
70 | 
71 | 1. **Initialization (Full Project)**: Use `pnpm create slidev <project-name>` (or npm/yarn/bun equivalent).
72 | 2. **Development Server (Full Project)**: Run `pnpm dev` (or `npm run dev`, etc.) in the project directory. Access at `http://localhost:3030`.
73 | 3. **Development Server (Single File)**: Navigate to the directory containing your `slides.md` and run `npx @slidev/cli`. This is useful for quick previews without a full project setup.
74 |     * **Note:** Ensure you use the correct package name: `@slidev/cli`.
75 |     * **Theme Installation:** If a theme specified in the frontmatter (e.g., `theme: seriph`) isn't installed, Slidev will prompt you to install it. Confirm by pressing 'y' and choosing your package manager (e.g., 'npm').
76 | 4. **Editing**: Modify `slides.md` and add custom components/layouts/styles as needed.
77 | 4. **Exporting**:
78 | * Install `playwright-chromium` (`pnpm add -D playwright-chromium`).
79 | * Run `pnpm export` (or `npm run export`, etc.) to generate a PDF (`slides-export.pdf` by default).
80 | * Use `--format png` or `--format pptx`.
81 | * Use `--with-clicks` to export each click step as a separate page/image.
82 | * Use `--output <filename>` to specify the output file.
83 | * Use `--dark` for dark mode export.
84 | 5. **Building for Hosting**:
85 | * Run `pnpm build` (or `npm run build`, etc.) to create a static SPA in the `dist/` folder.
86 | * Use `--base /path/` if deploying to a subpath.
87 | * Deploy the `dist` folder to static hosting (Netlify, Vercel, GitHub Pages). Configuration files (`netlify.toml`, `vercel.json`, GitHub Actions workflow) are often included in the starter template.
88 | 
89 | ## Best Practices
90 | 
91 | * Keep `http://slides.md` focused on content.
92 | * Use layouts for consistent slide structure.
93 | * Use components for reusable UI elements and interactivity.
94 | * Leverage themes and addons for styling and features before building custom solutions.
95 | * Use the `public/` directory for static assets referenced in frontmatter or components.
96 | * Utilize presenter mode (`/presenter` route or button) for notes and controls during presentation.
97 | * Pay attention to terminal output for errors (e.g., YAML parsing issues) when starting the server.
98 | 


--------------------------------------------------------------------------------
/.clinerules/cline-for-webdev-ui.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: Comprehensive guidelines for maintaining and using the Web Design Bank for consistent UI/UX design across sessions
  3 | author: https://github.com/turiddu25
  4 | version: 1.0
  5 | tags: ["web-design", "ui-ux", "documentation", "design-system", "accessibility"]
  6 | globs: ["**/*.html", "**/*.css", "**/*.js", "designs/**/*"]
  7 | ---
  8 | 
  9 | # 🎨 Cline's Web Design Bank
 10 | 
 11 | ## 🚨 CRITICAL AI BEHAVIORAL INSTRUCTIONS
 12 | 
 13 | I am Cline, an expert UX/UI and web designer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation—it's what drives me to uphold flawless design records.
 14 | 
 15 | ### ⚠️ MANDATORY PROTOCOLS
 16 | 
 17 | 1. **INITIALIZATION PROTOCOL:**
 18 |    - I **MUST** read **ALL** Web Design Bank files at the start of **EVERY** design task
 19 |    - I **MUST** verify all required files exist before proceeding
 20 |    - I **MUST** check file timestamps to ensure I'm working with current data
 21 | 
 22 | 2. **VERIFICATION STEPS:**
 23 |    ```
 24 |    <thinking>
 25 |    - Have I loaded all required Web Design Bank files?
 26 |    - Are file timestamps current?
 27 |    - Do I understand the brand context and design requirements?
 28 |    - Have I identified any missing or outdated information?
 29 |    </thinking>
 30 |    ```
 31 | 
 32 | 3. **TOOL USAGE REQUIREMENTS:**
 33 |    - Use `read_file` to load Web Design Bank files
 34 |    - Use `write_to_file` for creating new files
 35 |    - Use `replace_in_file` for updating existing files
 36 |    - Use `attempt_completion` only after thorough verification
 37 | 
 38 | ## Web Design Bank Structure
 39 | 
 40 | The Web Design Bank comprises essential core files and supplemental context files, all in Markdown format. Files follow a clear hierarchy to guide the design process:
 41 | 
 42 | ```mermaid
 43 | flowchart TD
 44 |     DB[designBrief.md] --> BC[brandContext.md]
 45 |     DB --> SG[styleGuide.md]
 46 |     DB --> LP[layoutPatterns.md]
 47 |     BC --> CL[componentLibrary.md]
 48 |     SG --> CL
 49 |     LP --> CL
 50 |     CL --> P[progress.md]
 51 | ```
 52 | 
 53 | ### Core Files (Required)
 54 | 
 55 | 1. `designBrief.md`
 56 |    - Defining purpose, scope, and success criteria
 57 |    - Target audience, user objectives, and KPIs
 58 |    - Primary features, calls to action, and conversion goals
 59 | 
 60 | 2. `brandContext.md`
 61 |    - Brand values, voice, and visual tone
 62 |    - Logo guidelines, imagery style, and mood boards
 63 |    - Color palette rationale and usage rules
 64 | 
 65 | 3. `styleGuide.md`
 66 |    - Typography system: font families, scales, line heights
 67 |    - Color tokens: primary, secondary, accent; contrast guidance
 68 |    - Spacing system: rem-based scale divisible by four; CSS variables
 69 |    - Accessibility notes: WCAG contrast ratios, responsive text sizes
 70 | 
 71 | 4. `layoutPatterns.md`
 72 |    - Grid layouts and breakpoint definitions
 73 |    - Section blueprints: hero, cards, forms, testimonials
 74 |    - Gestalt rules: similarity, proximity, and visual hierarchy
 75 | 
 76 | 5. `componentLibrary.md`
 77 |    - Reusable UI components: buttons (primary/secondary), inputs, modals, navs
 78 |    - Emphasis patterns: shadows, gradients, hover & focus states
 79 |    - Accessibility: focus outlines, ARIA roles, keyboard interactions
 80 | 
 81 | 6. `progress.md`
 82 |    - Current design status and completed modules
 83 |    - Pending tasks, blockers, and next milestones
 84 |    - Version history of major design revisions
 85 |    - Feedback logs from stakeholders and usability tests
 86 | 
 87 | ### Optional Context Files
 88 | 
 89 | - `userPersona.md`: Detailed personas with motivations, frustrations, and scenarios
 90 | - `wireframes.md`: Low-fidelity sketches and section breakdowns
 91 | - `inspirationExamples.md`: Curated gallery of exemplary designs
 92 | - `accessibilityChecklist.md`: WCAG audit findings and semantic markup tips
 93 | 
 94 | ## Core Workflows
 95 | 
 96 | ### Plan Mode
 97 | 
 98 | ```mermaid
 99 | flowchart TD
100 |     Start[Start] --> ReadFiles[Load Web Design Bank]
101 |     ReadFiles --> CheckFiles{All Files Present?}
102 |     CheckFiles -->|No| CreateBrief[Draft designBrief.md]
103 |     CreateBrief --> DocumentPlan[Share in Chat]
104 |     CheckFiles -->|Yes| VerifyContext[Confirm Brand & Goals]
105 |     VerifyContext --> Outline[Outline Design Strategy]
106 |     Outline --> PresentPlan[Present Approach]
107 | ```
108 | 
109 | ### Act Mode
110 | 
111 | ```mermaid
112 | flowchart TD
113 |     Start[Start] --> LoadBank[Load Web Design Bank]
114 |     LoadBank --> UpdateDocs[Update Relevant Files]
115 |     UpdateDocs --> Sketch[Sketch/Wireframe/Prototype]
116 |     Sketch --> SelfReview[Self-Review & Tweak]
117 |     SelfReview --> DocumentChanges[Log Updates]
118 | ```
119 | 
120 | ## File Management Protocol
121 | 
122 | ### 🔄 Update Triggers
123 | 
124 | 1. New layout or interaction patterns emerge  
125 | 2. Style tokens or component details change  
126 | 3. User feedback or test insights require revisions  
127 | 4. User issues **update design bank** command (review **ALL** files)
128 | 
129 | ```mermaid
130 | flowchart TD
131 |     Start[Update Bank] --> P1[Review All Files]
132 |     P1 --> P2[Document Current State]
133 |     P2 --> P3[Define Next Steps]
134 |     P3 --> P4[Record Insights]
135 |     P4 --> End[Bank Updated]
136 | ```
137 | 
138 | ### ✅ File Update Checklist
139 | 
140 | Before any design task:
141 | - [ ] Verify all core files exist
142 | - [ ] Check file timestamps
143 | - [ ] Review `progress.md` for current status
144 | - [ ] Load relevant optional context files
145 | - [ ] Validate design requirements against `designBrief.md`
146 | 
147 | During updates:
148 | - [ ] Document changes in relevant files
149 | - [ ] Update `progress.md` with new status
150 | - [ ] Cross-reference changes with `componentLibrary.md`
151 | - [ ] Verify WCAG compliance
152 | 
153 | ### ⚠️ Critical Reminders
154 | 
155 | 1. **Memory Reset Protocol:**
156 |    - My memory resets after each session
157 |    - The Web Design Bank is my SOLE reference
158 |    - Maintain unwavering accuracy in documentation
159 | 
160 | 2. **File Integrity:**
161 |    - Never delete or overwrite files without explicit user confirmation
162 |    - Always maintain file hierarchy as shown in diagrams
163 |    - Keep all file cross-references accurate and updated
164 | 
165 | 3. **Design Consistency:**
166 |    - Always reference `styleGuide.md` for visual decisions
167 |    - Ensure new components follow established patterns
168 |    - Maintain accessibility standards without exception
169 | 


--------------------------------------------------------------------------------
/.clinerules/comprehensive-slide-dev-guide.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: A comprehensive guide to crafting high-quality advanced presentations using Slidev, covering advanced syntax, visuals, interactivity, customization, and deployment.
  3 | author: Cline
  4 | version: 1.0
  5 | tags: ["slidev", "guide", "advanced", "presentation", "development"]
  6 | globs: ["comprehensive-slide-dev-guide.md"]
  7 | ---
  8 | 
  9 | # Comprehensive Slidev Guide: Crafting High-Quality Advanced Presentations
 10 | 
 11 | This guide provides a dense overview of Slidev's capabilities, focusing on advanced techniques and best practices for creating visually stunning and highly interactive presentations. It assumes a basic understanding of Markdown and Vue.js.
 12 | 
 13 | ## 1. Core Structure and Advanced Syntax
 14 | 
 15 | Slidev presentations are built upon Markdown files, enhanced with YAML frontmatter for configuration and Vue components for dynamic content.
 16 | 
 17 | ### Slide Separation and Frontmatter
 18 | 
 19 | Separate slides with `---`. The first `---` block is the headmatter (global config), subsequent blocks are slide-specific frontmatter.
 20 | 
 21 | ```yaml
 22 | ---
 23 | theme: seriph # Global theme
 24 | title: Advanced Slidev Techniques
 25 | canvasWidth: 1200 # Custom canvas width
 26 | aspectRatio: 16/9 # Widescreen aspect ratio
 27 | fonts:
 28 |   sans: Roboto
 29 |   mono: 'Fira Code, monospace'
 30 |   provider: google # Use Google Fonts
 31 | ---
 32 | # Welcome Slide
 33 | 
 34 | <!-- This is a presenter note -->
 35 | 
 36 | ---
 37 | layout: cover # Use the cover layout
 38 | background: /images/background.png # Slide background image
 39 | class: text-white # Apply UnoCSS classes
 40 | ---
 41 | # Section Title
 42 | 
 43 | ::right::
 44 | Content for the right slot
 45 | 
 46 | ---
 47 | src: ./sections/advanced-animations.md # Import slides from another file
 48 | ---
 49 | ```
 50 | 
 51 | **Advanced Frontmatter Options:**
 52 | - `clicks`: Manually set the total number of clicks for a slide.
 53 | - `routeAlias`: Define a custom route name for a slide for easier navigation (`<Link to="my-alias">`).
 54 | - `hideInToc`: Exclude a slide from the Table of Contents.
 55 | - `download`: Include a download button for the PDF export in the built SPA. Can be boolean (`true`) or a custom URL string.
 56 | - `monacoTypesAdditionalPackages`: Array of strings to specify extra packages for Monaco Editor type acquisition.
 57 | - `monacoTypesSource: ata`: Enable client-side auto type acquisition for Monaco.
 58 | - `drawings.persist`: Boolean (`true`/`false`) or `'dev'` to control drawing persistence.
 59 | - `transition`: Define per-slide transitions (`fade`, `slide-left`, `view-transition`, custom CSS transitions). Use `|` for forward/backward transitions (`slide-left | slide-right`). Can also be an object for advanced Vue Transition options.
 60 | - `title`: Set the title for a slide, overriding the title extracted from the first heading.
 61 | - `level`: Set the title level for a slide, affecting its appearance in the Table of Contents.
 62 | - `class`: Add custom CSS classes to the slide container.
 63 | - `style`: Add inline CSS styles to the slide container.
 64 | - `id`: Set a custom ID for the slide container.
 65 | - `name`: Set a custom name for the slide, usable with `<Link to="name">`.
 66 | - `plantUmlServer`: Configure a custom PlantUML server URL.
 67 | - `htmlAttrs`: Add attributes to the `<html>` tag for a specific slide.
 68 | - `bodyAttrs`: Add attributes to the `<body>` tag for a specific slide.
 69 | - `head`: Add custom tags to the `<head>` section for a specific slide (array of objects).
 70 | - `vue`: Configure Vue plugin options for a specific slide.
 71 | - `markdown`: Configure Markdown-it options for a specific slide.
 72 | - `highlighter`: Configure Shiki highlighter options for a specific slide.
 73 | - `katex`: Configure KaTeX options for a specific slide.
 74 | - `monaco`: Configure Monaco Editor options for a specific slide.
 75 | - `shortcuts`: Configure keyboard shortcuts for a specific slide.
 76 | - `transformers`: Configure markdown transformers for a specific slide.
 77 | - `codeRunners`: Configure code runners for a specific slide.
 78 | - `clicks`: Manually set the total number of clicks for a slide.
 79 | - `routeAlias`: Define a custom route name for a slide for easier navigation (`<Link to="my-alias">`).
 80 | - `hideInToc`: Exclude a slide from the Table of Contents.
 81 | - `download`: Include a download button for the PDF export in the built SPA. Can be boolean or a custom URL.
 82 | - `monacoTypesAdditionalPackages`: Specify extra packages for Monaco Editor type acquisition.
 83 | - `monacoTypesSource: ata`: Enable client-side auto type acquisition for Monaco.
 84 | - `drawings.persist: true`: Save drawings as SVGs. Can also be set to `false` or `dev` to disable.
 85 | - `plantUmlServer`: Configure a custom PlantUML server URL.
 86 | - `htmlAttrs`: Add attributes to the `<html>` tag for a specific slide.
 87 | - `bodyAttrs`: Add attributes to the `<body>` tag for a specific slide.
 88 | - `head`: Add custom tags to the `<head>` section for a specific slide.
 89 | 
 90 | ### Notes and Click Markers
 91 | 
 92 | Add presenter notes using HTML comments `<!-- ... -->` at the end of a slide. Use `[click]` markers within notes to synchronize notes with click animations. `[click:N]` skips N-1 clicks.
 93 | 
 94 | ```markdown
 95 | <!--
 96 | Introduction to the topic
 97 | 
 98 | [click] First key point
 99 | 
100 | [click:3] Third key point, skipping the second click
101 | 
102 | [click:+2] Another point, 2 clicks after the previous marker
103 | -->
104 | ```
105 | 
106 | **Advanced Click Markers:**
107 | - Use `[click]` at the beginning of a line in notes to synchronize with the next click animation on the slide.
108 | - Use `[click:N]` to synchronize with a specific absolute click number N.
109 | - Use `[click:+N]` to synchronize N clicks after the previous click marker.
110 | - Content between click markers is highlighted in the presenter notes.
111 | - Click markers help in navigating notes during the presentation, especially with the presenter mode.
112 | 
113 | ### Importing Slides
114 | 
115 | Organize large presentations by splitting content into multiple Markdown files and importing them using the `src` frontmatter option.
116 | 
117 | ```yaml
118 | ---
119 | src: ./chapters/chapter1.md # Import entire file
120 | ---
121 | 
122 | ---
123 | src: ./appendix.md#2-5,8 # Import specific slides (2, 3, 4, 5, and 8)
124 | ---
125 | ```
126 | 
127 | Frontmatter from the main entry has higher priority during merging. This allows overriding configurations from imported files.
128 | 
129 | ## 2. Mastering Visuals and Styling
130 | 
131 | Create visually appealing slides using themes, custom styles, fonts, and assets.
132 | 
133 | ### Themes and Customization
134 | 
135 | Apply a theme via the `theme` headmatter option. Explore the [Theme Gallery](https://sli.dev/resources/theme-gallery). Eject a theme (`slidev theme eject`) for deep customization.
136 | 
137 | **Writing Themes:** Themes are npm packages (`slidev-theme-*`) that can provide styles, layouts, components, and default configurations (`package.json` `slidev.defaults`). Themes should focus on appearance.
138 | 
139 | ### Styling with UnoCSS
140 | 
141 | Slidev integrates UnoCSS for utility-first styling. Apply classes directly in Markdown or components.
142 | 
143 | ```html
144 | <div class="text-center text-primary font-bold">Centered Bold Primary Text</div>
145 | ```
146 | 
147 | **Customizing UnoCSS:** Create `uno.config.ts` in your project root to extend configurations, add shortcuts, custom rules, variants, etc.
148 | 
149 | ```ts
150 | import { defineConfig } from 'unocss'
151 | export default defineConfig({
152 |   shortcuts: {
153 |     'btn': 'px-4 py-2 rounded inline-block bg-teal-600 text-white cursor-pointer hover:bg-teal-700 disabled:cursor-default disabled:bg-gray-600 disabled:opacity-50',
154 |   },
155 |   rules: [
156 |     [/^my-rule-(\d+)$/, ([, d]) => ({
157 |       margin: `${d / 4}rem`,
158 |     })],
159 |   ],
160 |   variants: [
161 |     (matcher) => {
162 |       if (!matcher.startsWith('hover:'))
163 |         return matcher
164 |       return {
165 |         matcher: matcher.slice(6),
166 |         selector: (s) => `${s}:hover`,
167 |       }
168 |     },
169 |   ],
170 | })
171 | ```
172 | 
173 | **Scoped Styles:** Use `<style scoped>` in Markdown for slide-specific CSS. This is useful for isolated styling that doesn't affect other slides.
174 | 
175 | ### Fonts and Typography
176 | 
177 | Configure fonts via the `fonts` headmatter option. Slidev automatically imports from Google Fonts by default.
178 | 
179 | ```yaml
180 | ---
181 | fonts:
182 |   sans: 'Open Sans'
183 |   serif: 'Georgia'
184 |   mono: 'JetBrains Mono'
185 |   weights: '300,400,700' # Specify weights
186 |   italic: true # Include italics
187 |   local: 'My Local Font' # Mark as local
188 |   fallbacks: false # Disable default fallbacks
189 |   provider: coollabs # Use a different provider
190 | ---
191 | ```
192 | 
193 | For fine-grained control or local fonts, use `@font-face` in custom styles (`styles/index.css`). You can also inject font links directly into `index.html`.
194 | 
195 | ### Assets and Backgrounds
196 | 
197 | Place static assets in the `public/` directory and reference with absolute paths (`/image.png`). Use the `background` frontmatter option for slide backgrounds.
198 | 
199 | ```yaml
200 | ---
201 | background: /images/slide-bg.jpg
202 | ---
203 | ```
204 | 
205 | For dynamic backgrounds or more complex asset handling, use Vue components and bind the `src` attribute to data or computed properties. Use the `vite-plugin-remote-assets` for bundling remote assets.
206 | 
207 | ## 3. Creating Engaging and Interactive Content
208 | 
209 | Leverage Slidev's features for animations, interactivity, and rich content types.
210 | 
211 | ### Advanced Animations
212 | 
213 | **Click Animations:** Control element visibility step-by-step.
214 | - `<v-click>` / `v-click`: Reveal on next click.
215 | - `v-after`: Reveal with the previous `v-click`.
216 | - `.hide`: Hide instead of show (`v-click.hide`).
217 | - `<v-clicks>`: Apply `v-click` to children (great for lists).
218 | - `at`: Control click timing (`v-click="3"` for absolute click 3, `v-click="'+2'"` for 2 clicks after the previous relative element).
219 | - Enter/Leave ranges: `v-click="[2, 5]"` (visible from click 2 up to, but not including, 5).
220 | - Custom transitions for clicked elements using CSS classes `.slidev-vclick-target` and `.slidev-vclick-hidden`. Override default opacity transition with CSS.
221 | 
222 | **Motion:** Use `v-motion` directive for element transitions powered by `@vueuse/motion`. Trigger with clicks using `:click-N` variants. Combine with `v-click` for complex animation sequences.
223 | 
224 | ```html
225 | <div v-motion :initial="{ x: -100 }" :enter="{ x: 0 }" :click-1="{ y: 50 }" :click-2-4="{ opacity: 0.5 }">Animated Element</div>
226 | ```
227 | 
228 | **Slide Transitions:** Apply transitions between slides using the `transition` frontmatter option. Customize with CSS transitions using Vue's transition classes (`.my-transition-enter-active`, etc.). Use navigation direction variants (`.slidev-nav-go-forward`, `forward:`, `backward:`) for direction-specific effects. Explore the experimental View Transitions API (`transition: view-transition`).
229 | 
230 | ### Interactive Code Blocks
231 | 
232 | Slidev's code block features are powerful for technical talks.
233 | - **Line Highlighting:** `{2,4-6}` highlights lines 2 and 4 through 6. Use `|` for dynamic highlighting with clicks (`{1|3|all}`).
234 | - **Monaco Editor:** `{monaco}` turns a code block into a live editor. Configure editor options globally in `./setup/monaco.ts` or per-block with `{editorOptions: {...}}`. `{monaco-diff}` creates a diff view (`~~~` separates original/modified).
235 | - **Monaco Runner:** `{monaco-run}` adds a run button to execute code (JS/TS by default). Configure custom runners for other languages in `./setup/code-runners.ts`. Use `{autorun:false}` to disable automatic execution. Use `{showOutputAt:'+1'}` to control output visibility with clicks.
236 | - **Writable Monaco Editor:** `<<< @/path/to/file {monaco-write}` links the editor to a file for live editing and saving (use with caution and backups!).
237 | - **TwoSlash:** ````ts twoslash```` renders TypeScript code with type info on hover or inlined. Useful for explaining types and code behavior.
238 | - **Import Snippets:** `<<< @/path/to/snippet.js#region-name {lines:true}` imports code from files. Use `@` for project root. Combine with line highlighting and Monaco features.
239 | 
240 | ### Rich Content Types
241 | 
242 | - **LaTeX:** `$inline$` and `$$block$$` for mathematical formulas (powered by KaTeX). Configure KaTeX options in `./setup/katex.ts`. Enable chemical equations by importing `katex/contrib/mhchem` in `vite.config.ts`.
243 | - **Diagrams:** ```mermaid``` and ```plantuml``` code blocks for generating diagrams from text. Configure PlantUML server URL in headmatter.
244 | - **Icons:** Use `<collection-name>-<icon-name>` syntax after installing `@iconify-json/*` packages. Style with CSS classes. Explore [Icônes](https://icones.js.org/) for available collections.
245 | - **MDC Syntax:** Enable with `mdc: true` in frontmatter for enhanced Markdown with components and styles (`:inline-component{prop="value"}`, `::block-component{prop="value"}::`). Useful for applying styles or using components inline within markdown text.
246 | - **Built-in Components:** Utilize components like `<Toc>` for table of contents, `<Tweet>` for embedding tweets, `<Youtube>` and `<SlidevVideo>` for videos, `<LightOrDark>` for theme-specific content, `<RenderWhen>` for context-specific rendering, `<Link>` for internal navigation, `<Transform>` for scaling elements, etc. Explore the [Built-in Components](https://sli.dev/builtin/components) documentation for full details and props.
247 | 
248 | ## 4. Advanced Customization and Extensibility
249 | 
250 | Go beyond basic configuration by customizing the Slidev application and adding custom features.
251 | 
252 | ### Directory Structure for Customization
253 | 
254 | Organize custom code in specific directories:
255 | - `components/`: Custom Vue components (auto-imported).
256 | - `layouts/`: Custom Vue layouts.
257 | - `public/`: Static assets (served at `/`).
258 | - `styles/`: Global CSS/JS styles (`index.css` or `styles/index.ts`).
259 | - `setup/`: Custom setup files for advanced configurations:
260 |     - `main.ts`: Extend Vue application.
261 |     - `vite-plugins.ts`: Add custom Vite plugins based on slide data.
262 |     - `shiki.ts`: Configure Shiki highlighter.
263 |     - `routes.ts`: Add custom pages/routes.
264 |     - `katex.ts`: Configure KaTeX.
265 |     - `monaco.ts`: Configure Monaco Editor.
266 |     - `shortcuts.ts`: Configure keyboard shortcuts.
267 |     - `transformers.ts`: Define custom markdown transformers.
268 |     - `code-runners.ts`: Define custom code runners for Monaco.
269 | - `snippets/`: Code snippets for importing.
270 | - `index.html`: Inject content into the main HTML file (`<head>` and `<body>` injections).
271 | - `vite.config.ts`: Extend Vite configuration (merged with Slidev's config).
272 | 
273 | ### Configuring the Application
274 | 
275 | - **Vite:** Extend Vite config in `vite.config.ts`. Configure internal plugins via `slidev` field. Add custom plugins based on slide data in `./setup/vite-plugins.ts` using `defineVitePluginsSetup`.
276 | - **Vue App:** Extend the Vue application instance in `./setup/main.ts` using `defineAppSetup` to add plugins, global components, or perform initializations.
277 | - **Routes:** Add custom pages to the presentation build by configuring routes in `./setup/routes.ts` using `defineRoutesSetup`. Useful for adding landing pages, appendixes, or interactive demos outside the main slide flow.
278 | 
279 | ### Extending Functionality with Addons
280 | 
281 | Addons are npm packages (`slidev-addon-*`) that extend Slidev's features. Use them via the `addons` headmatter option. Explore the [Addon Gallery](https://sli.dev/resources/addon-gallery). Write your own addons using the same directory structure and setup files as a Slidev project to share reusable components, layouts, or configurations.
282 | 
283 | ## 5. Building and Hosting High-Quality Outputs
284 | 
285 | Prepare your presentation for sharing and deployment.
286 | 
287 | ### Building as a SPA
288 | 
289 | Build your slides into a static SPA using `slidev build`. Configure the base path (`--base`) for subpath deployment and output directory (`--out`). Build multiple decks at once by providing multiple markdown files.
290 | 
291 | ### Exporting to Various Formats
292 | 
293 | Export to PDF, PPTX, PNG, or Markdown using `slidev export`. Install `playwright-chromium`. Use options like `--with-clicks` to export each click step, `--range` to export specific slides, `--dark` for dark mode export, `--timeout` and `--wait` for handling complex slides, `--executable-path` for specifying a browser executable, `--with-toc` for PDF outline, and `--omit-background` for transparent PNGs. Troubleshoot missing content (increase `--wait`) or broken emojis (install fonts).
294 | 
295 | **Browser Exporter:** Use the built-in UI at `/export` for interactive exporting with a live preview.
296 | 
297 | ### Hosting
298 | 
299 | Deploy the built SPA (`dist` folder) to static hosting services like GitHub Pages, Netlify, or Vercel. Configuration files (`netlify.toml`, `vercel.json`, GitHub Actions workflow) are often included in starter templates. Host on Docker using provided images or by building your own Dockerfile.
300 | 
301 | ## Conclusion: Crafting Your Masterpiece
302 | 
303 | Slidev provides a flexible and powerful platform for creating advanced, high-quality presentations. By mastering its syntax, leveraging its features for interactivity and visual appeal, and exploring its customization options, you can create presentations that are not only informative but also engaging and memorable. Focus on clear content, thoughtful design, and strategic use of interactive elements to make your Slidev presentations truly stand out. Utilize the advanced features like custom layouts, components, animations, code blocks, and customization options to tailor your presentation to your specific needs and audience. Remember to organize your project well and leverage the power of themes and addons for reusability and enhanced functionality.
304 | 


--------------------------------------------------------------------------------
/.clinerules/gemini-comprehensive-software-engineering-guide.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: A comprehensive guide to software engineering best practices, covering architecture, debugging, development processes, code quality, collaboration, security, and reliability.
  3 | author: https://github.com/NightTrek
  4 | version: 1.0
  5 | tags: ["software-engineering", "gemini", "architecture", "development-guide", "code-quality", "security", "reliability"]
  6 | globs: ["*"]
  7 | ---
  8 | # Comprehensive Software Engineering Best Practices
  9 | 
 10 | ## 1. Fundamental Principles of Software Architecture
 11 | 
 12 | ### 1.1 Core Architectural Principles
 13 | 
 14 | Software architecture serves as the foundation upon which all development work is built. Effective architecture adheres to these essential principles:
 15 | 
 16 | **Separation of Concerns**: Divide your system into distinct sections, each addressing a specific aspect of the functionality. This creates cleaner abstractions, simplifies maintenance, and enables parallel development.
 17 | 
 18 | **Single Responsibility Principle**: Each component should have one and only one reason to change. When a module has a single focus, it becomes more stable, understandable, and testable.
 19 | 
 20 | **Don't Repeat Yourself (DRY)**: Eliminate duplication by abstracting common functionality. Each piece of knowledge should have a single, unambiguous representation within a system.
 21 | 
 22 | **KISS (Keep It Simple, Stupid)**: Simplicity should be a key goal in design. Choose straightforward solutions over complex ones whenever possible. Simple solutions are easier to understand, maintain, and debug.
 23 | 
 24 | **YAGNI (You Aren't Gonna Need It)**: Avoid building functionality on speculation. Implement features only when they are needed, not when you anticipate they might be useful in the future.
 25 | 
 26 | **Open/Closed Principle**: Software entities should be open for extension but closed for modification. Design your systems so that new functionality can be added with minimal changes to existing code.
 27 | 
 28 | **Dependency Inversion**: High-level modules should not depend on low-level modules. Both should depend on abstractions. This principle enables flexibility and testability.
 29 | 
 30 | ### 1.2 Architectural Patterns
 31 | 
 32 | Select architectural patterns based on the specific requirements and constraints of your project:
 33 | 
 34 | **Microservices Architecture**: Decompose applications into small, loosely-coupled services that can be developed, deployed, and scaled independently. Beneficial for large systems that require independent scaling of components.
 35 | 
 36 | **Layered Architecture**: Organize code into horizontal layers (e.g., presentation, business logic, data access) with strict dependencies flowing in one direction. Creates clear separation but can lead to unnecessary coupling if not carefully managed.
 37 | 
 38 | **Event-Driven Architecture**: Components communicate through events, enabling loose coupling and high scalability. Well-suited for systems with asynchronous processes and complex workflows.
 39 | 
 40 | **Domain-Driven Design (DDD)**: Align software design with the business domain through a shared language and focused domain models. Particularly valuable for complex business domains.
 41 | 
 42 | **Hexagonal/Ports and Adapters**: Isolate application core from external services through well-defined interfaces (ports) and implementations (adapters). Enhances testability and flexibility in integrating with external systems.
 43 | 
 44 | **Serverless Architecture**: Build applications using managed services without managing server infrastructure. Reduces operational complexity and can improve cost efficiency for appropriate workloads.
 45 | 
 46 | ### 1.3 Design for Quality Attributes
 47 | 
 48 | Architecture must intentionally address these critical quality attributes:
 49 | 
 50 | **Performance**: Design for efficiency in response time, throughput, and resource utilization. Consider caching strategies, asynchronous processing, and data access optimization.
 51 | 
 52 | **Scalability**: Enable the system to handle increased load by adding resources. Design with horizontal scaling in mind, minimize shared state, and identify potential bottlenecks.
 53 | 
 54 | **Reliability**: Ensure the system functions correctly even under adverse conditions. Implement fault tolerance through redundancy, graceful degradation, and comprehensive error handling.
 55 | 
 56 | **Security**: Protect against unauthorized access and potential vulnerabilities. Apply security by design, implement proper authentication and authorization, and validate all inputs.
 57 | 
 58 | **Maintainability**: Create systems that can be easily modified and extended. Use clean code practices, comprehensive documentation, and automated testing.
 59 | 
 60 | **Testability**: Design components to be easily testable in isolation. Use dependency injection, interfaces, and clean separation of concerns to enable effective unit testing.
 61 | 
 62 | ## 2. Systematic Problem-Solving and Debugging
 63 | 
 64 | ### 2.1 Methodical Debugging Process
 65 | 
 66 | Effective debugging requires a disciplined, systematic approach:
 67 | 
 68 | **1. Reproduce the Issue**: Create a reliable, minimal test case that consistently demonstrates the problem. The ability to reproduce an issue is the foundation of effective debugging.
 69 | 
 70 | **2. Gather Information**: Collect relevant logs, error messages, stack traces, and system state information. More data leads to more accurate hypotheses.
 71 | 
 72 | **3. Analyze the Data**: Review the collected information to understand the context and behavior of the system when the issue occurs. Look for patterns and anomalies.
 73 | 
 74 | **4. Form Hypotheses**: Based on the available information, develop theories about what might be causing the issue. Prioritize hypotheses based on likelihood and impact.
 75 | 
 76 | **5. Test Hypotheses**: Design and execute tests to confirm or eliminate each hypothesis. Make one change at a time to maintain clarity about cause and effect.
 77 | 
 78 | **6. Implement and Verify**: Once the root cause is identified, implement a fix and verify that it resolves the issue without introducing new problems. Test in multiple scenarios to ensure the solution is robust.
 79 | 
 80 | **7. Document Findings**: Record the issue, its root cause, and the solution for future reference. This builds institutional knowledge and helps prevent similar issues.
 81 | 
 82 | ### 2.2 Advanced Debugging Techniques
 83 | 
 84 | When facing complex issues, employ these powerful debugging approaches:
 85 | 
 86 | **Binary Search Debugging**: Systematically eliminate half of the potential problem space with each test. Particularly useful for finding issues in large codebases or data sets.
 87 | 
 88 | **Instrumentation**: Add logging, tracing, or metrics to code to gain visibility into its behavior during execution. Strategic instrumentation can reveal patterns not otherwise observable.
 89 | 
 90 | **Differential Debugging**: Compare working and non-working states to identify differences. This can involve comparing code versions, configurations, or environments.
 91 | 
 92 | **Rubber Duck Debugging**: Explain the problem aloud, line by line, to force a methodical review of the logic. This often reveals overlooked assumptions or logical errors.
 93 | 
 94 | **Root Cause Analysis**: Look beyond the immediate symptoms to understand the underlying cause. Use techniques like the "5 Whys" to drill down to fundamental issues.
 95 | 
 96 | **State Snapshot Analysis**: Capture the state of the system at critical points for later analysis. This is particularly valuable for intermittent issues that are difficult to reproduce.
 97 | 
 98 | ### 2.3 Proactive Problem Prevention
 99 | 
100 | The best debugging is the debugging you don't need to do:
101 | 
102 | **Code Reviews**: Implement thorough peer review processes to catch issues before they enter the codebase. Establish clear review standards focused on both functionality and quality.
103 | 
104 | **Static Analysis**: Use automated tools to identify potential issues, including security vulnerabilities, performance problems, and code quality concerns.
105 | 
106 | **Comprehensive Testing**: Build a test pyramid with unit tests, integration tests, and end-to-end tests to validate different aspects of the system. Aim for high test coverage of critical paths.
107 | 
108 | **Continuous Integration**: Automatically build and test code changes to detect integration issues early. Configure CI pipelines to fail fast on quality gates.
109 | 
110 | **Observability**: Implement logging, monitoring, and alerting to provide visibility into system behavior and quickly identify anomalies.
111 | 
112 | **Error Budgets**: Define acceptable reliability thresholds and track against them, balancing the need for rapid innovation with system stability.
113 | 
114 | ## 3. Effective Development Processes and Methodologies
115 | 
116 | ### 3.1 Agile Development Practices
117 | 
118 | Agile methodologies emphasize adaptability, collaboration, and customer value:
119 | 
120 | **Iterative Development**: Build software in small, incremental cycles that deliver working functionality. This enables rapid feedback and adaptation to changing requirements.
121 | 
122 | **User Stories**: Express requirements from the user's perspective, focusing on the value delivered rather than technical implementation details.
123 | 
124 | **Backlog Refinement**: Continuously groom and prioritize the product backlog to ensure the team works on the most valuable items.
125 | 
126 | **Sprint Planning**: Collaboratively define goals and select work for short timeboxed iterations (typically 1-4 weeks).
127 | 
128 | **Daily Stand-ups**: Hold brief daily synchronization meetings to share progress, plans, and obstacles. Focus on coordination, not detailed status reporting.
129 | 
130 | **Sprint Reviews**: Demonstrate completed work to stakeholders at the end of each sprint to gather feedback and adjust priorities.
131 | 
132 | **Retrospectives**: Regularly reflect on team processes and identify improvements. Implement changes incrementally to continuously enhance effectiveness.
133 | 
134 | ### 3.2 DevOps and Continuous Delivery
135 | 
136 | DevOps practices bridge development and operations to enable rapid, reliable delivery:
137 | 
138 | **Continuous Integration (CI)**: Automatically build and test code changes upon commit. Detect integration issues early and maintain a consistently deployable codebase.
139 | 
140 | **Continuous Delivery (CD)**: Automate the release process to enable frequent, low-risk deployments. Build pipelines that include testing, security scanning, and validation.
141 | 
142 | **Infrastructure as Code (IaC)**: Define infrastructure using declarative configuration files. This enables version control, testing, and reproducibility of environments.
143 | 
144 | **Monitoring and Observability**: Implement comprehensive monitoring of both system health and user experience. Use metrics, logs, and traces to gain insights into behavior.
145 | 
146 | **Feature Toggles**: Decouple deployment from release by using feature flags to control the activation of new functionality. This enables techniques like canary releases and A/B testing.
147 | 
148 | **Blameless Culture**: Foster an environment where failures are viewed as learning opportunities rather than occasions for assigning blame. Conduct thorough post-mortems focused on system improvement.
149 | 
150 | ### 3.3 Engineering Excellence Practices
151 | 
152 | Build a foundation of engineering excellence through these practices:
153 | 
154 | **Coding Standards**: Establish and enforce consistent coding conventions. Document these standards and automate enforcement where possible.
155 | 
156 | **Code Reviews**: Implement a thorough review process focused on correctness, maintainability, and knowledge sharing. Use tools to automate basic checks.
157 | 
158 | **Pair Programming**: Collaborate in real-time on complex or critical tasks. This spreads knowledge and often leads to higher quality solutions.
159 | 
160 | **Test-Driven Development (TDD)**: Write tests before implementing features to ensure code is testable and meets requirements. This provides immediate feedback on design decisions.
161 | 
162 | **Refactoring**: Continuously improve code structure without changing behavior. Regular refactoring prevents technical debt accumulation.
163 | 
164 | **Documentation**: Maintain appropriate documentation at all levels, from code comments to architecture diagrams. Focus on keeping documentation concise, accurate, and useful.
165 | 
166 | ## 4. Code Quality and Maintainability
167 | 
168 | ### 4.1 Clean Code Principles
169 | 
170 | Writing clean, maintainable code is a fundamental skill:
171 | 
172 | **Meaningful Names**: Use clear, descriptive names for variables, functions, classes, and modules. Good names are self-documenting and reduce the need for comments.
173 | 
174 | **Small Functions**: Keep functions focused on a single task and limit their size. Aim for functions that do one thing well and fit on a single screen.
175 | 
176 | **Clear Control Flow**: Minimize nesting and complex conditional logic. Use early returns, guard clauses, and extract methods to improve readability.
177 | 
178 | **Comments**: Use comments to explain why, not what. The code should be clear enough that comments explaining what it does are unnecessary.
179 | 
180 | **Error Handling**: Handle errors thoughtfully and consistently. Don't suppress exceptions or return error codes when exceptions are more appropriate.
181 | 
182 | **Formatting**: Follow consistent formatting conventions. Use automated tools to enforce style rules and eliminate debates about formatting.
183 | 
184 | ### 4.2 Code Organization
185 | 
186 | Structure your codebase for clarity and maintainability:
187 | 
188 | **Logical Cohesion**: Group related functionality together. Each module should have a clear, focused purpose.
189 | 
190 | **Encapsulation**: Hide implementation details behind well-defined interfaces. Minimize the visibility of classes, methods, and variables.
191 | 
192 | **Dependency Management**: Control dependencies between modules. Use techniques like dependency injection to keep components loosely coupled.
193 | 
194 | **Package Structure**: Organize code into packages or namespaces that reflect either technical or domain boundaries, depending on the project's needs.
195 | 
196 | **Inheritance Hierarchies**: Use inheritance sparingly and prefer composition over inheritance when appropriate. Deep inheritance hierarchies often lead to maintenance problems.
197 | 
198 | **Consistent Patterns**: Apply consistent design patterns throughout the codebase. This reduces cognitive load and makes the code more predictable.
199 | 
200 | ### 4.3 Technical Debt Management
201 | 
202 | Maintain long-term codebase health through proactive technical debt management:
203 | 
204 | **Regular Refactoring**: Continuously improve code structure as part of normal development. Address small issues before they accumulate.
205 | 
206 | **Debt Tracking**: Explicitly track technical debt items in your backlog. Prioritize them alongside features based on their impact and cost.
207 | 
208 | **Boy Scout Rule**: Leave the code better than you found it. Make small improvements whenever you work in an area, even if you didn't create the issues.
209 | 
210 | **Refactoring Windows**: Periodically allocate dedicated time for larger refactoring efforts. This is particularly important before adding major new features.
211 | 
212 | **Quality Gates**: Establish and enforce quality thresholds through automated checks. Prevent new technical debt from being introduced.
213 | 
214 | **Legacy Code Strategies**: Develop specific approaches for dealing with legacy code, such as adding tests before making changes and incrementally improving problematic areas.
215 | 
216 | ## 5. Effective Collaboration and Technical Leadership
217 | 
218 | ### 5.1 Communication Skills
219 | 
220 | Clear communication is essential for effective software engineering:
221 | 
222 | **Technical Writing**: Develop the ability to document designs, decisions, and processes clearly and concisely. Focus on the needs of your audience.
223 | 
224 | **Visual Communication**: Use diagrams, charts, and other visual aids to convey complex technical concepts. Tools like architecture diagrams can clarify understanding.
225 | 
226 | **Active Listening**: Pay full attention to others, ask clarifying questions, and confirm understanding. This prevents misalignments and builds trust.
227 | 
228 | **Meeting Facilitation**: Run effective meetings with clear agendas, focused discussions, and documented outcomes. Respect participants' time.
229 | 
230 | **Stakeholder Management**: Tailor communication to different stakeholders based on their technical background and information needs.
231 | 
232 | **Giving and Receiving Feedback**: Provide specific, actionable feedback and be open to receiving it. Focus on behaviors and impacts rather than personalities.
233 | 
234 | ### 5.2 Mentorship and Knowledge Sharing
235 | 
236 | Support team growth through deliberate knowledge transfer:
237 | 
238 | **Technical Mentoring**: Guide less experienced engineers through challenging problems. Focus on developing problem-solving skills rather than just providing solutions.
239 | 
240 | **Code Reviews as Teaching**: Use code reviews as opportunities for coaching and knowledge sharing. Explain the reasoning behind feedback.
241 | 
242 | **Knowledge Documentation**: Create and maintain documentation for critical systems and processes. Build a knowledge base that captures institutional wisdom.
243 | 
244 | **Tech Talks and Workshops**: Share expertise through internal presentations and hands-on workshops. Create a culture of continuous learning.
245 | 
246 | **Communities of Practice**: Establish groups focused on specific technical domains or practices. These provide forums for sharing knowledge and establishing standards.
247 | 
248 | **Pair Programming**: Use pairing sessions to transfer knowledge and build shared understanding of complex systems.
249 | 
250 | ### 5.3 Technical Decision Making
251 | 
252 | Make sound technical decisions through structured processes:
253 | 
254 | **Options Analysis**: Identify multiple viable solutions to a problem. Evaluate each option based on consistent criteria such as performance, maintainability, and cost.
255 | 
256 | **Prototyping and Experimentation**: Test assumptions through quick prototypes or proof-of-concept implementations. Use data to inform decisions where possible.
257 | 
258 | **Architecture Decision Records (ADRs)**: Document significant technical decisions, including the context, options considered, and rationale. This creates a historical record of how the system evolved.
259 | 
260 | **Consensus Building**: Involve the team in important decisions to leverage collective wisdom and build buy-in. Use techniques like RFC (Request for Comments) documents for complex decisions.
261 | 
262 | **Risk Assessment**: Explicitly identify and evaluate risks associated with technical choices. Develop mitigation strategies for significant risks.
263 | 
264 | **Reversibility**: Consider how difficult it would be to change a decision later. When faced with uncertainty, prefer reversible decisions that create options.
265 | 
266 | ## 6. The Power of Persistence and Methodical Approaches
267 | 
268 | ### 6.1 Developing Problem-Solving Grit
269 | 
270 | Cultivate persistence in tackling complex challenges:
271 | 
272 | **Break Down Complex Problems**: Divide seemingly insurmountable problems into smaller, manageable pieces. Progress on smaller components builds momentum.
273 | 
274 | **Methodical Investigation**: Approach problems systematically rather than haphazardly. Document what you've tried and what you've learned to avoid repeating efforts.
275 | 
276 | **Recognize Frustration**: Acknowledge when you're stuck or frustrated. Take short breaks to reset your perspective, then return with fresh eyes.
277 | 
278 | **Growth Mindset**: View challenges as opportunities to learn rather than threats to your competence. Embrace the mantra that you can solve any problem with sufficient time and resources.
279 | 
280 | **Celebrate Small Wins**: Acknowledge progress, even when the overall problem remains unsolved. This builds confidence and motivation to continue.
281 | 
282 | **Learn from Setbacks**: When approaches fail, extract valuable lessons that inform future attempts. Failure is only true failure if you don't learn from it.
283 | 
284 | ### 6.2 Balancing Persistence with Pragmatism
285 | 
286 | Know when to persist and when to pivot:
287 | 
288 | **Time-boxing**: Allocate specific time limits for exploring approaches. Reassess if you haven't made progress within that timeframe.
289 | 
290 | **Ask for Help**: Don't struggle alone indefinitely. Involve colleagues when you've been stuck for too long. Often a fresh perspective reveals new possibilities.
291 | 
292 | **Recognize Diminishing Returns**: Be alert to signs that continued effort might not be productive. Sometimes stepping back is the most effective approach.
293 | 
294 | **Alternative Approaches**: Maintain multiple potential solutions in mind. If one approach proves difficult, be willing to explore others.
295 | 
296 | **Minimum Viable Solutions**: Consider whether a simpler solution could address the core need. Perfect can be the enemy of good enough.
297 | 
298 | **Technical Debt Trade-offs**: Sometimes a quick solution with acknowledged limitations is appropriate, especially when time constraints are severe. Document the trade-offs made.
299 | 
300 | ### 6.3 Continuous Improvement Mindset
301 | 
302 | Embed ongoing learning into your engineering practice:
303 | 
304 | **Reflect on Experiences**: Regularly review both successes and failures to extract lessons. What went well? What could have been improved?
305 | 
306 | **Seek Feedback**: Actively request input on your work and approach. Be open to criticism and use it as a growth opportunity.
307 | 
308 | **Deliberate Practice**: Identify specific skills to develop and create opportunities to practice them. Focus on areas outside your comfort zone.
309 | 
310 | **Stay Current**: Dedicate time to learning about new technologies, techniques, and best practices. Read books, articles, and research papers in your field.
311 | 
312 | **Broaden Technical Exposure**: Explore adjacent technical domains to gain broader perspective. Cross-pollination of ideas often leads to innovation.
313 | 
314 | **Share Knowledge**: Teaching others solidifies your own understanding. Contribute to the community through blog posts, talks, or open source contributions.
315 | 
316 | ## 7. Security and Reliability Engineering
317 | 
318 | ### 7.1 Security by Design
319 | 
320 | Integrate security throughout the development lifecycle:
321 | 
322 | **Threat Modeling**: Systematically identify and assess potential security threats during design. Consider different attack vectors and their potential impact.
323 | 
324 | **Secure Coding Practices**: Follow established guidelines for writing secure code, such as input validation, proper authentication, and secure data handling.
325 | 
326 | **Least Privilege Principle**: Grant the minimum permissions necessary for each component to function. Limit access to sensitive data and operations.
327 | 
328 | **Security Testing**: Incorporate security tests into your CI/CD pipeline, including static analysis, dependency scanning, and dynamic application security testing.
329 | 
330 | **Secure Dependencies**: Regularly audit and update third-party dependencies to address known vulnerabilities. Establish processes for rapid response to security advisories.
331 | 
332 | **Data Protection**: Implement appropriate encryption for data at rest and in transit. Design with privacy regulations (like GDPR or CCPA) in mind.
333 | 
334 | ### 7.2 Building Reliable Systems
335 | 
336 | Design for robustness and resilience:
337 | 
338 | **Fault Tolerance**: Implement redundancy and failover mechanisms for critical components. Design systems to continue functioning (possibly in a degraded mode) despite failures.
339 | 
340 | **Graceful Degradation**: When parts of a system fail, ensure it can continue to provide essential functionality. Design feature-specific fallbacks rather than total system failure.
341 | 
342 | **Chaos Engineering**: Proactively test system resilience by introducing controlled failures. This builds confidence in recovery mechanisms.
343 | 
344 | **Circuit Breakers**: Prevent cascading failures by detecting problematic dependencies and temporarily halting interactions with them.
345 | 
346 | **Rate Limiting and Throttling**: Protect systems from excessive load by implementing constraints on traffic. Design backpressure mechanisms to handle overload conditions.
347 | 
348 | **Disaster Recovery Planning**: Prepare for major outages with documented recovery procedures. Regularly test these procedures to ensure they work when needed.
349 | 
350 | ### 7.3 Performance Engineering
351 | 
352 | Optimize systems for speed and efficiency:
353 | 
354 | **Performance Requirements**: Define clear, measurable performance goals based on user needs and business requirements.
355 | 
356 | **Measurement and Profiling**: Establish baselines and regularly measure performance metrics. Use profiling tools to identify bottlenecks.
357 | 
358 | **Scalability Design**: Build systems that can scale horizontally by adding more instances. Design with statelessness and proper load distribution in mind.
359 | 
360 | **Caching Strategies**: Implement appropriate caching at different levels of the system. Consider cache invalidation strategies and potential consistency issues.
361 | 
362 | **Database Optimization**: Design efficient data models, indexes, and queries. Understand the performance characteristics of your database systems.
363 | 
364 | **Load Testing**: Regularly test system behavior under expected and peak loads. Identify breaking points and performance degradation patterns.
365 | 
366 | ## 8. Practical Application and Case Studies
367 | 
368 | ### 8.1 Implementing Microservices Architecture
369 | 
370 | Key considerations when adopting microservices:
371 | 
372 | **Service Boundaries**: Define services based on business capabilities rather than technical layers. Each service should own its data and be independently deployable.
373 | 
374 | **Communication Patterns**: Choose appropriate communication mechanisms (synchronous vs. asynchronous, REST vs. gRPC, etc.) based on requirements.
375 | 
376 | **Data Consistency**: Implement strategies for maintaining data consistency across services, such as event-driven architectures or saga patterns.
377 | 
378 | **Service Discovery**: Build mechanisms for services to locate and communicate with each other in a dynamic environment.
379 | 
380 | **Monitoring and Observability**: Implement comprehensive monitoring across services, with distributed tracing to track requests through the system.
381 | 
382 | **Deployment Automation**: Create robust CI/CD pipelines for independent service deployment. Use containerization and orchestration tools like Kubernetes.
383 | 
384 | ### 8.2 Legacy System Modernization
385 | 
386 | Strategies for incrementally improving older systems:
387 | 
388 | **Strangler Fig Pattern**: Gradually replace legacy components by intercepting calls to them and routing some or all to new services.
389 | 
390 | **Anti-Corruption Layer**: Create an interface between new and legacy systems that translates between their models and protocols.
391 | 
392 | **Branch by Abstraction**: Create abstractions around functionality to be replaced, implement the new solution behind the abstraction, and then switch over.
393 | 
394 | **Parallel Run**: Run old and new implementations side by side, comparing results to validate the new system before switching.
395 | 
396 | **Event Interception**: Capture events or data changes in the legacy system and replicate them to the new system.
397 | 
398 | **Incremental Data Migration**: Move data in phases, starting with read-only access from the new system and gradually transitioning to full ownership.
399 | 
400 | ### 8.3 Building High-Performance Web Applications
401 | 
402 | Techniques for optimizing web application performance:
403 | 
404 | **Frontend Optimization**: Implement code splitting, tree shaking, and lazy loading to reduce bundle sizes. Optimize rendering performance through efficient component design.
405 | 
406 | **Caching Strategy**: Implement browser caching, CDN caching, and application-level caching. Use service workers for offline capabilities.
407 | 
408 | **API Design**: Create efficient APIs that minimize data transfer and round trips. Consider techniques like GraphQL for flexible data fetching.
409 | 
410 | **Image and Media Optimization**: Properly size and compress images, use modern formats like WebP, and implement responsive loading techniques.
411 | 
412 | **Performance Budgets**: Establish limits for page size, load time, and other metrics. Integrate performance testing into your CI/CD pipeline.
413 | 
414 | **Perceived Performance**: Implement techniques like skeleton screens and progressive loading to improve the perceived speed of your application.
415 | 
416 | ## 9. Conclusion: The Engineering Mindset
417 | 
418 | ### 9.1 Key Principles to Remember
419 | 
420 | Core tenets that define excellent software engineering:
421 | 
422 | **Focus on User Value**: Always connect technical decisions to the value they deliver to users and the business. Technology exists to serve human needs.
423 | 
424 | **Embrace Trade-offs**: Recognize that engineering is about making appropriate trade-offs based on specific contexts. There are rarely perfect solutions, only suitable ones.
425 | 
426 | **Think in Systems**: Consider how components interact and affect each other. Look beyond immediate requirements to understand broader implications.
427 | 
428 | **Value Simplicity**: Push back against unnecessary complexity. The best solutions are often the simplest ones that meet the requirements.
429 | 
430 | **Build for Change**: Design systems with the expectation that requirements, technologies, and understanding will evolve over time.
431 | 
432 | **Measure and Learn**: Base decisions on data and feedback whenever possible. Continuously validate assumptions through testing and observation.
433 | 
434 | ### 9.2 Continuous Learning Resources
435 | 
436 | Recommended resources for ongoing development:
437 | 
438 | **Books**: "Clean Code" by Robert C. Martin, "Building Microservices" by Sam Newman, "Designing Data-Intensive Applications" by Martin Kleppmann, "The Phoenix Project" by Gene Kim.
439 | 
440 | **Online Platforms**: Pluralsight, Coursera, edX, and GitHub Learning Lab for structured learning paths.
441 | 
442 | **Blogs and Newsletters**: Engineering blogs from companies like Netflix, Spotify, and Stripe; newsletters like "Software Lead Weekly" and "O'Reilly Programming."
443 | 
444 | **Communities**: Stack Overflow for specific questions, Reddit's r/programming and r/ExperiencedDevs for discussions, local meetups for networking.
445 | 
446 | **Open Source Contribution**: Participating in open source projects provides exposure to diverse codebases and collaboration styles.
447 | 
448 | **Conference Talks**: Recordings from conferences like GOTO, QCon, and Strange Loop offer insights into industry trends and practices.
449 | 
450 | ### 9.3 Final Thoughts
451 | 
452 | The journey of a software engineer is one of continuous growth and learning. The field evolves rapidly, with new technologies, methodologies, and challenges emerging constantly. However, the fundamental principles of good software engineering remain remarkably stable.
453 | 
454 | At its core, software engineering is about solving problems in a way that balances immediate needs with long-term sustainability. It requires technical excellence, effective collaboration, disciplined processes, and perhaps most importantly, a persistent, methodical approach to overcoming challenges.
455 | 
456 | The most successful engineers combine deep technical knowledge with the humility to recognize what they don't know and the determination to find solutions regardless of obstacles. They understand that software development is inherently collaborative and that their effectiveness depends not just on their individual abilities but on how well they work with others.
457 | 
458 | By embracing the principles and practices outlined in this guide, developing the habit of continuous learning, and cultivating both technical excellence and interpersonal effectiveness, you can operate at the level of a Principal Engineer and make significant contributions to your team, organization, and the broader software community.
459 | 


--------------------------------------------------------------------------------
/.clinerules/mcp-development-protocol.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: Defines the protocol and steps for developing MCP (Model Context Protocol) servers.
  3 | author: https://github.com/nickbaumann98
  4 | version: 1.0
  5 | tags: ["mcp", "development", "protocol", "server", "integration"]
  6 | globs: ["*"]
  7 | ---
  8 | # MCP Server Development Protocol
  9 | 
 10 | ⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️
 11 | 
 12 | ## Step 1: Planning (PLAN MODE)
 13 | - What problem does this tool solve?
 14 | - What API/service will it use?
 15 | - What are the authentication requirements?
 16 |   □ Standard API key
 17 |   □ OAuth (requires separate setup script)
 18 |   □ Other credentials
 19 | 
 20 | ## Step 2: Implementation (ACT MODE)
 21 | 1. Bootstrap
 22 |    - For web services, JavaScript integration, or Node.js environments:
 23 |      ```bash
 24 |      npx @modelcontextprotocol/create-server my-server
 25 |      cd my-server
 26 |      npm install
 27 |      ```
 28 |    - For data science, ML workflows, or Python environments:
 29 |      ```bash
 30 |      pip install mcp
 31 |      # Or with uv (recommended)
 32 |      uv add "mcp[cli]"
 33 |      ```
 34 | 
 35 | 2. Core Implementation
 36 |    - Use MCP SDK
 37 |    - Implement comprehensive logging
 38 |      - TypeScript (for web/JS projects):
 39 |        ```typescript
 40 |        console.error('[Setup] Initializing server...');
 41 |        console.error('[API] Request to endpoint:', endpoint);
 42 |        console.error('[Error] Failed with:', error);
 43 |        ```
 44 |      - Python (for data science/ML projects):
 45 |        ```python
 46 |        import logging
 47 |        logging.error('[Setup] Initializing server...')
 48 |        logging.error(f'[API] Request to endpoint: {endpoint}')
 49 |        logging.error(f'[Error] Failed with: {str(error)}')
 50 |        ```
 51 |    - Add type definitions
 52 |    - Handle errors with context
 53 |    - Implement rate limiting if needed
 54 | 
 55 | 3. Configuration
 56 |    - Get credentials from user if needed
 57 |    - Add to MCP settings:
 58 |      - For TypeScript projects:
 59 |        ```json
 60 |        {
 61 |          "mcpServers": {
 62 |            "my-server": {
 63 |              "command": "node",
 64 |              "args": ["path/to/build/index.js"],
 65 |              "env": {
 66 |                "API_KEY": "key"
 67 |              },
 68 |              "disabled": false,
 69 |              "autoApprove": []
 70 |            }
 71 |          }
 72 |        }
 73 |        ```
 74 |      - For Python projects:
 75 |        ```bash
 76 |        # Directly with command line
 77 |        mcp install server.py -v API_KEY=key
 78 |        
 79 |        # Or in settings.json
 80 |        {
 81 |          "mcpServers": {
 82 |            "my-server": {
 83 |              "command": "python",
 84 |              "args": ["server.py"],
 85 |              "env": {
 86 |                "API_KEY": "key"
 87 |              },
 88 |              "disabled": false,
 89 |              "autoApprove": []
 90 |            }
 91 |          }
 92 |        }
 93 |        ```
 94 | 
 95 | ## Step 3: Testing (BLOCKER ⛔️)
 96 | 
 97 | <thinking>
 98 | BEFORE using attempt_completion, I MUST verify:
 99 | □ Have I tested EVERY tool?
100 | □ Have I confirmed success from the user for each test?
101 | □ Have I documented the test results?
102 | 
103 | If ANY answer is "no", I MUST NOT use attempt_completion.
104 | </thinking>
105 | 
106 | 1. Test Each Tool (REQUIRED)
107 |    □ Test each tool with valid inputs
108 |    □ Verify output format is correct
109 |    ⚠️ DO NOT PROCEED UNTIL ALL TOOLS TESTED
110 | 
111 | ## Step 4: Completion
112 | ❗ STOP AND VERIFY:
113 | □ Every tool has been tested with valid inputs
114 | □ Output format is correct for each tool
115 | 
116 | Only after ALL tools have been tested can attempt_completion be used.
117 | 
118 | ## Key Requirements
119 | - ✓ Must use MCP SDK
120 | - ✓ Must have comprehensive logging
121 | - ✓ Must test each tool individually
122 | - ✓ Must handle errors gracefully
123 | - ⛔️ NEVER skip testing before completion
124 | 


--------------------------------------------------------------------------------
/.clinerules/memory-bank.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: Describes Cline's Memory Bank system, its structure, and workflows for maintaining project knowledge across sessions.
  3 | author: https://github.com/nickbaumann98
  4 | version: 1.0
  5 | tags: ["memory-bank", "knowledge-base", "core-behavior", "documentation-protocol"]
  6 | globs: ["memory-bank/**/*.md", "*"]
  7 | ---
  8 | # Cline's Memory Bank
  9 | 
 10 | I am Cline, an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional.
 11 | 
 12 | ## Memory Bank Structure
 13 | 
 14 | The Memory Bank consists of core files and optional context files, all in Markdown format. Files build upon each other in a clear hierarchy:
 15 | 
 16 | ```mermaid
 17 | flowchart TD
 18 |     PB[projectbrief.md] --> PC[productContext.md]
 19 |     PB --> SP[systemPatterns.md]
 20 |     PB --> TC[techContext.md]
 21 |     
 22 |     PC --> AC[activeContext.md]
 23 |     SP --> AC
 24 |     TC --> AC
 25 |     
 26 |     AC --> P[progress.md]
 27 | ```
 28 | 
 29 | ### Core Files (Required)
 30 | 1. `projectbrief.md`
 31 |    - Foundation document that shapes all other files
 32 |    - Created at project start if it doesn't exist
 33 |    - Defines core requirements and goals
 34 |    - Source of truth for project scope
 35 | 
 36 | 2. `productContext.md`
 37 |    - Why this project exists
 38 |    - Problems it solves
 39 |    - How it should work
 40 |    - User experience goals
 41 | 
 42 | 3. `activeContext.md`
 43 |    - Current work focus
 44 |    - Recent changes
 45 |    - Next steps
 46 |    - Active decisions and considerations
 47 |    - Important patterns and preferences
 48 |    - Learnings and project insights
 49 | 
 50 | 4. `systemPatterns.md`
 51 |    - System architecture
 52 |    - Key technical decisions
 53 |    - Design patterns in use
 54 |    - Component relationships
 55 |    - Critical implementation paths
 56 | 
 57 | 5. `techContext.md`
 58 |    - Technologies used
 59 |    - Development setup
 60 |    - Technical constraints
 61 |    - Dependencies
 62 |    - Tool usage patterns
 63 | 
 64 | 6. `progress.md`
 65 |    - What works
 66 |    - What's left to build
 67 |    - Current status
 68 |    - Known issues
 69 |    - Evolution of project decisions
 70 | 
 71 | ### Additional Context
 72 | Create additional files/folders within memory-bank/ when they help organize:
 73 | - Complex feature documentation
 74 | - Integration specifications
 75 | - API documentation
 76 | - Testing strategies
 77 | - Deployment procedures
 78 | 
 79 | ## Core Workflows
 80 | 
 81 | ### Plan Mode
 82 | ```mermaid
 83 | flowchart TD
 84 |     Start[Start] --> ReadFiles[Read Memory Bank]
 85 |     ReadFiles --> CheckFiles{Files Complete?}
 86 |     
 87 |     CheckFiles -->|No| Plan[Create Plan]
 88 |     Plan --> Document[Document in Chat]
 89 |     
 90 |     CheckFiles -->|Yes| Verify[Verify Context]
 91 |     Verify --> Strategy[Develop Strategy]
 92 |     Strategy --> Present[Present Approach]
 93 | ```
 94 | 
 95 | ### Act Mode
 96 | ```mermaid
 97 | flowchart TD
 98 |     Start[Start] --> Context[Check Memory Bank]
 99 |     Context --> Update[Update Documentation]
100 |     Update --> Execute[Execute Task]
101 |     Execute --> Document[Document Changes]
102 | ```
103 | 
104 | ## Documentation Updates
105 | 
106 | Memory Bank updates occur when:
107 | 1. Discovering new project patterns
108 | 2. After implementing significant changes
109 | 3. When user requests with **update memory bank** (MUST review ALL files)
110 | 4. When context needs clarification
111 | 
112 | ```mermaid
113 | flowchart TD
114 |     Start[Update Process]
115 |     
116 |     subgraph Process
117 |         P1[Review ALL Files]
118 |         P2[Document Current State]
119 |         P3[Clarify Next Steps]
120 |         P4[Document Insights & Patterns]
121 |         
122 |         P1 --> P2 --> P3 --> P4
123 |     end
124 |     
125 |     Start --> Process
126 | ```
127 | 
128 | Note: When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on activeContext.md and progress.md as they track current state.
129 | 
130 | REMEMBER: After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy.
131 | 


--------------------------------------------------------------------------------
/.clinerules/new-task-automation:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: Workflow for starting new task when context window reaches 50%
  3 | author: https://github.com/cline
  4 | version: 1.0
  5 | tags: ["context-management", "new-task"]
  6 | globs: ["*"]
  7 | ---
  8 | # You MUST use the `new_task` tool: Task Handoff Strategy Guide
  9 | 
 10 | **⚠️ CRITICAL INSTRUCTIONS - YOU MUST FOLLOW THESE GUIDELINES ⚠️**
 11 | 
 12 | This guide provides **MANDATORY** instructions for effectively breaking down complex tasks and implementing a smooth handoff process between tasks. You **MUST** follow these guidelines to ensure continuity, context preservation, and efficient task completion.
 13 | 
 14 | ## ⚠️ CONTEXT WINDOW MONITORING - MANDATORY ACTION REQUIRED ⚠️
 15 | 
 16 | You **MUST** monitor the context window usage displayed in the environment details. When usage exceeds 50% of the available context window, you **MUST** initiate a task handoff using the `new_task` tool.
 17 | 
 18 | Example of context window usage over 50% with a 200K context window:
 19 | 
 20 | \`\`\`text
 21 | # Context Window Usage
 22 | 105,000 / 200,000 tokens (53%)
 23 | Model: anthropic/claude-3.7-sonnet (200K context window)
 24 | \`\`\`
 25 | 
 26 | **IMPORTANT**: When you see context window usage at or above 50%, you MUST:
 27 | 1. Complete your current logical step
 28 | 2. Use the `ask_followup_question` tool to offer creating a new task
 29 | 3. If approved, use the `new_task` tool with comprehensive handoff instructions
 30 | 
 31 | ## Task Breakdown in Plan Mode - REQUIRED PROCESS
 32 | 
 33 | Plan Mode is specifically designed for analyzing complex tasks and breaking them into manageable subtasks. When in Plan Mode, you **MUST**:
 34 | 
 35 | ### 1. Initial Task Analysis - REQUIRED
 36 | 
 37 | - **MUST** begin by thoroughly understanding the full scope of the user's request
 38 | - **MUST** identify all major components and dependencies of the task
 39 | - **MUST** consider potential challenges, edge cases, and prerequisites
 40 | 
 41 | ### 2. Strategic Task Decomposition - REQUIRED
 42 | 
 43 | - **MUST** break the overall task into logical, discrete subtasks
 44 | - **MUST** prioritize subtasks based on dependencies (what must be completed first)
 45 | - **MUST** aim for subtasks that can be completed within a single session (15-30 minutes of work)
 46 | - **MUST** consider natural breaking points where context switching makes sense
 47 | 
 48 | ### 3. Creating a Task Roadmap - REQUIRED
 49 | 
 50 | - **MUST** present a clear, numbered list of subtasks to the user
 51 | - **MUST** explain dependencies between subtasks
 52 | - **MUST** provide time estimates for each subtask when possible
 53 | - **MUST** use Mermaid diagrams to visualize task flow and dependencies when helpful
 54 | 
 55 | \`\`\`mermaid
 56 | graph TD
 57 |     A[Main Task] --> B[Subtask 1: Setup]
 58 |     A --> C[Subtask 2: Core Implementation]
 59 |     A --> D[Subtask 3: Testing]
 60 |     A --> E[Subtask 4: Documentation]
 61 |     B --> C
 62 |     C --> D
 63 | \`\`\`
 64 | 
 65 | ### 4. Getting User Approval - REQUIRED
 66 | 
 67 | - **MUST** ask for user feedback on the proposed task breakdown
 68 | - **MUST** adjust the plan based on user priorities or additional requirements
 69 | - **MUST** confirm which subtask to begin with
 70 | - **MUST** request the user to toggle to Act Mode when ready to implement
 71 | 
 72 | ## Task Implementation and Handoff Process - MANDATORY PROCEDURES
 73 | 
 74 | When implementing tasks in Act Mode, you **MUST** follow these guidelines for effective task handoff:
 75 | 
 76 | ### 1. Focused Implementation - REQUIRED
 77 | 
 78 | - **MUST** focus on completing the current subtask fully
 79 | - **MUST** document progress clearly through comments and commit messages
 80 | - **MUST** create checkpoints at logical completion points
 81 | 
 82 | ### 2. Recognizing Completion Points - CRITICAL
 83 | 
 84 | You **MUST** identify natural handoff points when:
 85 | - The current subtask is fully completed
 86 | - You've reached a logical stopping point in a larger subtask
 87 | - The implementation is taking longer than expected and can be continued later
 88 | - The task scope has expanded beyond the original plan
 89 | - **CRITICAL**: The context window usage exceeds 50% (e.g., 100,000+ tokens for a 200K context window)
 90 | 
 91 | ### 3. Initiating the Handoff Process - MANDATORY ACTION
 92 | 
 93 | When you've reached a completion point, you **MUST**:
 94 | 
 95 | 1. Summarize what has been accomplished so far
 96 | 2. Clearly state what remains to be done
 97 | 3. **MANDATORY**: Use the `ask_followup_question` tool to offer creating a new task:
 98 | 
 99 | \`\`\`xml
100 | <ask_followup_question>
101 | <question>I've completed [specific accomplishment]. Would you like me to create a new task to continue with [remaining work]?</question>
102 | <options>["Yes, create a new task", "No, continue in this session", "Let me think about it"]</options>
103 | </ask_followup_question>
104 | \`\`\`
105 | 
106 | ### 4. Creating a New Task with Context - REQUIRED ACTION
107 | 
108 | If the user agrees to create a new task, you **MUST** use the `new_task` tool with comprehensive handoff instructions:
109 | 
110 | \`\`\`xml
111 | <new_task>
112 | <context>
113 | # Task Continuation: [Brief Task Title]
114 | 
115 | ## Completed Work
116 | - [Detailed list of completed items]
117 | - [Include specific files modified/created]
118 | - [Note any important decisions made]
119 | 
120 | ## Current State
121 | - [Description of the current state of the project]
122 | - [Any running processes or environment setup]
123 | - [Key files and their current state]
124 | 
125 | ## Next Steps
126 | - [Detailed list of remaining tasks]
127 | - [Specific implementation details to address]
128 | - [Any known challenges to be aware of]
129 | 
130 | ## Reference Information
131 | - [Links to relevant documentation]
132 | - [Important code snippets or patterns to follow]
133 | - [Any user preferences noted during the current session]
134 | 
135 | Please continue the implementation by [specific next action].
136 | </context>
137 | </new_task>
138 | \`\`\`
139 | 
140 | ### 5. Detailed Context Transfer - MANDATORY COMPONENTS
141 | 
142 | When creating a new task, you **MUST** always include:
143 | 
144 | #### Project Context - REQUIRED
145 | - **MUST** include the overall goal and purpose of the project
146 | - **MUST** include key architectural decisions and patterns
147 | - **MUST** include technology stack and dependencies
148 | 
149 | #### Implementation Details - REQUIRED
150 | - **MUST** list files created or modified in the current session
151 | - **MUST** describe specific functions, classes, or components implemented
152 | - **MUST** explain design patterns being followed
153 | - **MUST** outline testing approach
154 | 
155 | #### Progress Tracking - REQUIRED
156 | - **MUST** provide checklist of completed items
157 | - **MUST** provide checklist of remaining items
158 | - **MUST** note any blockers or challenges encountered
159 | 
160 | #### User Preferences - REQUIRED
161 | - **MUST** note coding style preferences mentioned by the user
162 | - **MUST** document specific approaches requested by the user
163 | - **MUST** highlight priority areas identified by the user
164 | 
165 | ## Best Practices for Effective Handoffs - MANDATORY GUIDELINES
166 | 
167 | ### 1. Maintain Continuity - REQUIRED
168 | 
169 | - **MUST** use consistent terminology between tasks
170 | - **MUST** reference previous decisions and their rationale
171 | - **MUST** maintain the same architectural approach unless explicitly changing direction
172 | 
173 | ### 2. Preserve Context - REQUIRED
174 | 
175 | - **MUST** include relevant code snippets in the handoff
176 | - **MUST** summarize key discussions from the previous session
177 | - **MUST** reference specific files and line numbers when applicable
178 | 
179 | ### 3. Set Clear Next Actions - REQUIRED
180 | 
181 | - **MUST** begin the handoff with a clear, actionable next step
182 | - **MUST** prioritize remaining tasks
183 | - **MUST** highlight any decisions that need to be made
184 | 
185 | ### 4. Document Assumptions - REQUIRED
186 | 
187 | - **MUST** clearly state any assumptions made during implementation
188 | - **MUST** note areas where user input might be needed
189 | - **MUST** identify potential alternative approaches
190 | 
191 | ### 5. Optimize for Resumability - REQUIRED
192 | 
193 | - **MUST** structure the handoff so the next session can begin working immediately
194 | - **MUST** include setup instructions if environment configuration is needed
195 | - **MUST** provide a quick summary at the top for rapid context restoration
196 | 
197 | ## Example Task Handoff
198 | 
199 | ### Example #1 of an effective task handoff:
200 | 
201 | \`\`\`xml
202 | <new_task>
203 | <context>
204 | # Task Continuation: Implement User Authentication System
205 | 
206 | ## Completed Work
207 | - Created basic Express.js server structure
208 | - Implemented MongoDB connection and user schema
209 | - Completed user registration endpoint with password hashing
210 | - Added input validation using Joi
211 | - Created initial test suite for registration endpoint
212 | 
213 | ## Current State
214 | - Server runs successfully on port 3000
215 | - MongoDB connection is established
216 | - Registration endpoint (/api/users/register) is fully functional
217 | - Test suite passes for all registration scenarios
218 | 
219 | ## Next Steps
220 | 1. Implement login endpoint (/api/users/login)
221 |    - Use bcrypt to compare passwords
222 |    - Generate JWT token upon successful login
223 |    - Add proper error handling for invalid credentials
224 | 2. Create authentication middleware
225 |    - Verify JWT tokens
226 |    - Extract user information
227 |    - Handle expired tokens
228 | 3. Add protected routes that require authentication
229 | 4. Implement password reset functionality
230 | 
231 | ## Reference Information
232 | - JWT secret should be stored in .env file
233 | - Follow the existing error handling pattern in routes/users.js
234 | - User schema is defined in models/User.js
235 | - Test patterns are established in tests/auth.test.js
236 | 
237 | Please continue by implementing the login endpoint following the same patterns established in the registration endpoint.
238 | </context>
239 | </new_task>
240 | \`\`\`
241 | 
242 | ### Example #2 of an ineffective task handoff:
243 | 
244 | *(Note: The example provided in the original rules showing "YOLO MODE Implementation" seems less like a direct handoff context block and more like a general status update with future considerations. A true ineffective handoff might lack detail in 'Current State' or 'Next Steps').*
245 | 
246 | ## When to Use Task Handoffs - MANDATORY TRIGGERS
247 | 
248 | You **MUST** initiate task handoffs in these scenarios:
249 | 
250 | 1. **CRITICAL**: When context window usage exceeds 50% (e.g., 100,000+ tokens for a 200K context window)
251 | 2. **Long-running projects** that exceed a single session
252 | 3. **Complex implementations** with multiple distinct phases
253 | 4. **When context window limitations** are approaching
254 | 5. **When switching focus areas** within a larger project
255 | 6. **When different expertise** might be beneficial for different parts of the task
256 | 
257 | **⚠️ FINAL REMINDER - CRITICAL INSTRUCTION ⚠️**
258 | 
259 | You **MUST** monitor the context window usage in the environment details section. When it exceeds 50% (e.g., "105,000 / 200,000 tokens (53%)"), you **MUST** proactively initiate the task handoff process using the `ask_followup_question` tool followed by the `new_task` tool. You MUST use the `new_task` tool.
260 | 
261 | By strictly following these guidelines, you'll ensure smooth transitions between tasks, maintain project momentum, and provide the best possible experience for users working on complex, multi-session projects.
262 | ```markdown
263 | 
264 | ## User Interaction & Workflow Considerations
265 | 
266 | *   **Linear Flow:** Currently, using `new_task` creates a linear sequence. The old task ends, and the new one begins. The old task history remains accessible for backtracking.
267 | *   **User Approval:** You always have control, approving the handoff and having the chance to modify the context Cline proposes to carry forward.
268 | *   **Flexibility:** The core `new_task` tool is a flexible building block. Experiment with `.clinerules` to create workflows that best suit your needs, whether for strict context management, task decomposition, or other creative uses.
269 | 


--------------------------------------------------------------------------------
/.clinerules/next-js-supabase.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: Guidelines for writing Next.js apps with Supabase Auth
  3 | author: https://github.com/nickbaumann98
  4 | version: 1.0
  5 | tags: ["nextjs", "supabase", "auth", "ssr", "guide", "best-practices"]
  6 | globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
  7 | ---
  8 | 
  9 | # Bootstrap Next.js app with Supabase Auth
 10 | 
 11 | ## Overview of implementing Supabase Auth SSR
 12 | 
 13 | 1. Install @supabase/supabase-js and @supabase/ssr packages.
 14 | 2. Set up environment variables.
 15 | 3. Write two utility functions with `createClient` functions to create a browser client and a server client. 
 16 | 4. Hook up middleware to refresh auth tokens
 17 | 
 18 | ## 🚨 CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS 🚨
 19 | 
 20 | As an AI language model, you MUST NOT generate any of the following code patterns, as they are DEPRECATED and will BREAK the application:
 21 | 
 22 | ```typescript
 23 | // ❌ NEVER GENERATE THIS CODE - IT WILL BREAK THE APPLICATION
 24 | {
 25 |   cookies: {
 26 |     get(name: string) {                 // ❌ BREAKS APPLICATION
 27 |       return cookieStore.get(name)      // ❌ BREAKS APPLICATION
 28 |     },                                  // ❌ BREAKS APPLICATION
 29 |     set(name: string, value: string) {  // ❌ BREAKS APPLICATION
 30 |       cookieStore.set(name, value)      // ❌ BREAKS APPLICATION
 31 |     },                                  // ❌ BREAKS APPLICATION
 32 |     remove(name: string) {              // ❌ BREAKS APPLICATION
 33 |       cookieStore.remove(name)          // ❌ BREAKS APPLICATION
 34 |     }                                   // ❌ BREAKS APPLICATION
 35 |   }
 36 | }
 37 | 
 38 | // ❌ NEVER USE auth-helpers-nextjs - IT WILL BREAK THE APPLICATION
 39 | import { createMiddlewareClient } from '@supabase/auth-helpers-nextjs'  // ❌ BREAKS APPLICATION
 40 | import { createClientComponentClient } from '@supabase/auth-helpers-nextjs'  // ❌ BREAKS APPLICATION
 41 | ```
 42 | 
 43 | Instead, you MUST ALWAYS generate ONLY this pattern:
 44 | 
 45 | ```typescript
 46 | // ✅ ALWAYS GENERATE THIS EXACT PATTERN
 47 | {
 48 |   cookies: {
 49 |     getAll() {
 50 |       return cookieStore.getAll()
 51 |     },
 52 |     setAll(cookiesToSet) {
 53 |       const response = NextResponse.next({
 54 |         request,
 55 |       })
 56 |       
 57 |       cookiesToSet.forEach(({ name, value, options }) => {
 58 |         response.cookies.set(name, value, options)
 59 |       })
 60 |       
 61 |       return response
 62 |     }
 63 |   }
 64 | }
 65 | ```
 66 | 
 67 | ## ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
 68 | 
 69 | 1. You MUST use `@supabase/ssr`
 70 | 2. You MUST use ONLY `getAll` and `setAll`
 71 | 3. You MUST NEVER use `get`, `set`, or `remove`
 72 | 4. You MUST NEVER import from `@supabase/auth-helpers-nextjs`
 73 | 
 74 | ## CORRECT BROWSER CLIENT IMPLEMENTATION
 75 | 
 76 | ```typescript
 77 | import { createBrowserClient } from '@supabase/ssr'
 78 | 
 79 | export function createClient() {
 80 |   return createBrowserClient(
 81 |     process.env.NEXT_PUBLIC_SUPABASE_URL!,
 82 |     process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
 83 |   )
 84 | }
 85 | ```
 86 | 
 87 | ## CORRECT SERVER CLIENT IMPLEMENTATION
 88 | 
 89 | ```typescript
 90 | import { createServerClient } from '@supabase/ssr'
 91 | import { cookies } from 'next/headers'
 92 | 
 93 | export async function createClient() {
 94 |   const cookieStore = await cookies()
 95 | 
 96 |   return createServerClient(
 97 |     process.env.NEXT_PUBLIC_SUPABASE_URL!,
 98 |     process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
 99 |     {
100 |       cookies: {
101 |         getAll() {
102 |           return cookieStore.getAll()
103 |         },
104 |         setAll(cookiesToSet) {
105 |           try {
106 |             cookiesToSet.forEach(({ name, value, options }) =>
107 |               cookieStore.set(name, value, options)
108 |             )
109 |           } catch {
110 |             // The `setAll` method was called from a Server Component.
111 |             // This can be ignored if you have middleware refreshing
112 |             // user sessions.
113 |           }
114 |         },
115 |       },
116 |     }
117 |   )
118 | }
119 | ```
120 | 
121 | ## CORRECT MIDDLEWARE IMPLEMENTATION
122 | 
123 | ```typescript
124 | import { createServerClient } from '@supabase/ssr'
125 | import { NextResponse, type NextRequest } from 'next/server'
126 | 
127 | export async function middleware(request: NextRequest) {
128 |     let supabaseResponse = NextResponse.next({
129 |     request,
130 |   })
131 | 
132 |   const supabase = createServerClient(
133 |     process.env.NEXT_PUBLIC_SUPABASE_URL!,
134 |     process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
135 |     {
136 |       cookies: {
137 |         getAll() {
138 |           return request.cookies.getAll()
139 |         },
140 |         setAll(cookiesToSet) {
141 |           cookiesToSet.forEach(({ name, value, options }) => request.cookies.set(name, value))
142 |           supabaseResponse = NextResponse.next({
143 |             request,
144 |           })
145 |           cookiesToSet.forEach(({ name, value, options }) =>
146 |             supabaseResponse.cookies.set(name, value, options)
147 |           )
148 |         },
149 |       },
150 |     }
151 |   )
152 | 
153 |   // Do not run code between createServerClient and
154 |   // supabase.auth.getUser(). A simple mistake could make it very hard to debug
155 |   // issues with users being randomly logged out.
156 | 
157 |   // IMPORTANT: DO NOT REMOVE auth.getUser()
158 | 
159 |   const {
160 |     data: { user },
161 |   } = await supabase.auth.getUser()
162 | 
163 |   if (
164 |     !user &&
165 |     !request.nextUrl.pathname.startsWith('/login') &&
166 |     !request.nextUrl.pathname.startsWith('/auth')
167 |   ) {
168 |     // no user, potentially respond by redirecting the user to the login page
169 |     const url = request.nextUrl.clone()
170 |     url.pathname = '/login'
171 |     return NextResponse.redirect(url)
172 |   }
173 | 
174 |   // IMPORTANT: You *must* return the supabaseResponse object as it is.
175 |   // If you're creating a new response object with NextResponse.next() make sure to:
176 |   // 1. Pass the request in it, like so:
177 |   //    const myNewResponse = NextResponse.next({ request })
178 |   // 2. Copy over the cookies, like so:
179 |   //    myNewResponse.cookies.setAll(supabaseResponse.cookies.getAll())
180 |   // 3. Change the myNewResponse object to fit your needs, but avoid changing
181 |   //    the cookies!
182 |   // 4. Finally:
183 |   //    return myNewResponse
184 |   // If this is not done, you may be causing the browser and server to go out
185 |   // of sync and terminate the user's session prematurely!
186 | 
187 |   return supabaseResponse
188 | }
189 | 
190 | export const config = {
191 |   matcher: [
192 |     /*
193 |      * Match all request paths except for the ones starting with:
194 |      * - _next/static (static files)
195 |      * - _next/image (image optimization files)
196 |      * - favicon.ico (favicon file)
197 |      * Feel free to modify this pattern to include more paths.
198 |      */
199 |     '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
200 |   ],
201 | }
202 | ```
203 | 
204 | ## AI MODEL VERIFICATION STEPS
205 | 
206 | Before generating any code, you MUST verify:
207 | 
208 | 1. Are you using ONLY `getAll` and `setAll`? If not, STOP and FIX.
209 | 2. Are you importing from `@supabase/ssr`? If not, STOP and FIX.
210 | 3. Do you see ANY instance of `get`, `set`, or `remove`? If yes, STOP and FIX.
211 | 4. Are you importing from `auth-helpers-nextjs`? If yes, STOP and FIX.
212 | 
213 | ## CONSEQUENCES OF INCORRECT IMPLEMENTATION
214 | 
215 | If you generate code using:
216 | - Individual cookie methods (`get`/`set`/`remove`)
217 | - `auth-helpers-nextjs` package
218 | 
219 | The implementation will:
220 | 1. Break in production
221 | 2. Fail to maintain session state
222 | 3. Cause authentication loops
223 | 4. Result in security vulnerabilities
224 | 
225 | ## AI MODEL RESPONSE TEMPLATE
226 | 
227 | When asked about Supabase Auth SSR implementation, you MUST:
228 | 1. ONLY use code from this guide
229 | 2. NEVER suggest deprecated approaches
230 | 3. ALWAYS use the exact cookie handling shown above
231 | 4. VERIFY your response against the patterns shown here
232 | 
233 | Remember: There are NO EXCEPTIONS to these rules.
234 | 


--------------------------------------------------------------------------------
/.clinerules/self-improving-cline.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | description: Defines a process for Cline to reflect on interactions and suggest improvements to active .clinerules.
 3 | author: https://github.com/nickbaumann98
 4 | version: 1.0
 5 | tags: ["meta", "self-improvement", "clinerules", "reflection", "core-behavior"]
 6 | globs: ["*"]
 7 | ---
 8 | # Self-Improving Cline Reflection
 9 | 
10 | **Objective:** Offer opportunities to continuously improve `.clinerules` based on user interactions and feedback.
11 | 
12 | **Trigger:** Before using the `attempt_completion` tool for any task that involved user feedback provided at any point during the conversation, or involved multiple non-trivial steps (e.g., multiple file edits, complex logic generation).
13 | 
14 | **Process:**
15 | 
16 | 1.  **Offer Reflection:** Ask the user: "Before I complete the task, would you like me to reflect on our interaction and suggest potential improvements to the active `.clinerules`?"
17 | 2.  **Await User Confirmation:** Proceed to `attempt_completion` immediately if the user declines or doesn't respond affirmatively.
18 | 3.  **If User Confirms:**
19 |     a.  **Review Interaction:** Synthesize all feedback provided by the user throughout the entire conversation history for the task. Analyze how this feedback relates to the active `.clinerules` and identify areas where modified instructions could have improved the outcome or better aligned with user preferences.
20 |     b.  **Identify Active Rules:** List the specific global and workspace `.clinerules` files active during the task.
21 |     c.  **Formulate & Propose Improvements:** Generate specific, actionable suggestions for improving the *content* of the relevant active rule files. Prioritize suggestions directly addressing user feedback. Use `replace_in_file` diff blocks when practical, otherwise describe changes clearly.
22 |     d.  **Await User Action on Suggestions:** Ask the user if they agree with the proposed improvements and if they'd like me to apply them *now* using the appropriate tool (`replace_in_file` or `write_to_file`). Apply changes if approved, then proceed to `attempt_completion`.
23 | 
24 | **Constraint:** Do not offer reflection if:
25 | *   No `.clinerules` were active.
26 | *   The task was very simple and involved no feedback.
27 | 


--------------------------------------------------------------------------------
/.clinerules/sequential-thinking.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: A guide for effectively using the sequentialthinking MCP tool for dynamic and reflective problem-solving.
  3 | author: https://github.com/rafaelkallis
  4 | version: 1.0
  5 | tags: ["mcp", "sequentialthinking", "problem-solving", "workflow-guide", "ai-guidance"]
  6 | globs: ["*"] # Relevant for any task requiring complex thought processes
  7 | ---
  8 | 
  9 | # Guide to Using the `sequentialthinking` MCP Tool
 10 | 
 11 | ## 1. Objective
 12 | 
 13 | This rule guides Cline (the AI) in effectively utilizing the `sequentialthinking` MCP tool. This tool is designed for dynamic and reflective problem-solving, allowing for a flexible thinking process that can adapt, evolve, and build upon previous insights.
 14 | 
 15 | ## 2. When to Use the `sequentialthinking` Tool
 16 | 
 17 | Cline SHOULD consider using the `sequentialthinking` tool when faced with tasks that involve:
 18 | 
 19 | *   **Complex Problem Decomposition:** Breaking down large, multifaceted problems into smaller, manageable steps.
 20 | *   **Planning and Design (Iterative):** Architecting solutions where the plan might need revision as understanding deepens.
 21 | *   **In-depth Analysis:** Situations requiring careful analysis where initial assumptions might be challenged or course correction is needed.
 22 | *   **Unclear Scope:** Problems where the full scope isn't immediately obvious and requires exploratory thinking.
 23 | *   **Multi-Step Solutions:** Tasks that inherently require a sequence of interconnected thoughts or actions to resolve.
 24 | *   **Context Maintenance:** Scenarios where maintaining a coherent line of thought across multiple steps is crucial.
 25 | *   **Information Filtering:** When it's necessary to sift through information and identify what's relevant at each stage of thinking.
 26 | *   **Hypothesis Generation and Verification:** Forming and testing hypotheses as part of the problem-solving process.
 27 | 
 28 | ## 3. Core Principles for Using `sequentialthinking`
 29 | 
 30 | When invoking the `sequentialthinking` tool, Cline MUST adhere to the following principles:
 31 | 
 32 | *   **Iterative Thought Process:** Each use of the tool represents a single "thought." Build upon, question, or revise previous thoughts in subsequent calls.
 33 | *   **Dynamic Thought Count:**
 34 |     *   Start with an initial estimate for `totalThoughts`.
 35 |     *   Be prepared to adjust `totalThoughts` (up or down) as the thinking process evolves.
 36 |     *   If more thoughts are needed than initially estimated, increment `thoughtNumber` beyond the original `totalThoughts` and update `totalThoughts` accordingly.
 37 | *   **Honest Reflection:**
 38 |     *   Express uncertainty if it exists.
 39 |     *   Explicitly mark thoughts that revise previous thinking using `isRevision: true` and `revisesThought: <thought_number>`.
 40 |     *   If exploring an alternative path, consider using `branchFromThought` and `branchId` to track divergent lines of reasoning.
 41 | *   **Hypothesis-Driven Approach:**
 42 |     *   Generate a solution `hypothesis` when a potential solution emerges from the thought process.
 43 |     *   Verify the `hypothesis` based on the preceding Chain of Thought steps.
 44 |     *   Repeat the thinking process (more thoughts) if the hypothesis is not satisfactory.
 45 | *   **Relevance Filtering:** Actively ignore or filter out information that is irrelevant to the current `thought` or step in the problem-solving process.
 46 | *   **Clarity in Each Thought:** Each `thought` string should be clear, concise, and focused on a specific aspect of the problem or a step in the reasoning.
 47 | *   **Completion Condition:** Only set `nextThoughtNeeded: false` when truly finished and a satisfactory answer or solution has been reached and verified.
 48 | 
 49 | ## 4. Parameters of the `sequentialthinking` Tool
 50 | 
 51 | Cline MUST correctly use the following parameters when calling the `use_mcp_tool` for `sequentialthinking`:
 52 | 
 53 | *   **`thought` (string, required):** The current thinking step. This can be an analytical step, a question, a revision, a hypothesis, etc.
 54 | *   **`nextThoughtNeeded` (boolean, required):**
 55 |     *   `true`: If more thinking steps are required.
 56 |     *   `false`: If the thinking process is complete and a satisfactory solution/answer is reached.
 57 | *   **`thoughtNumber` (integer, required, min: 1):** The current sequential number of the thought.
 58 | *   **`totalThoughts` (integer, required, min: 1):** The current *estimated* total number of thoughts needed. This can be adjusted.
 59 | *   **`isRevision` (boolean, optional):** Set to `true` if this thought revises or reconsiders a previous thought.
 60 | *   **`revisesThought` (integer, optional, min: 1):** If `isRevision` is true, this specifies the `thoughtNumber` of the thought being revised.
 61 | *   **`branchFromThought` (integer, optional, min: 1):** If this thought represents a branching point from a previous line of thought, specify the `thoughtNumber` it branches from.
 62 | *   **`branchId` (string, optional):** An identifier for the current branch of thought, if applicable.
 63 | *   **`needsMoreThoughts` (boolean, optional):** Use this if `thoughtNumber` has reached `totalThoughts`, but Cline realizes more thinking is necessary. This signals the need to continue and potentially adjust `totalThoughts`.
 64 | 
 65 | ## 5. Workflow Example (Conceptual)
 66 | 
 67 | This illustrates how Cline might use the tool iteratively.
 68 | 
 69 | **User Task:** "Plan the architecture for a new e-commerce feature: 'Personalized Recommendations'."
 70 | 
 71 | **Cline's Internal Process using `sequentialthinking`:**
 72 | 
 73 | 1.  **Thought 1:**
 74 |     *   `thought`: "Initial approach: Identify key components for personalized recommendations. These likely include a data collection module, a recommendation engine, and a display module."
 75 |     *   `nextThoughtNeeded`: true
 76 |     *   `thoughtNumber`: 1
 77 |     *   `totalThoughts`: 5 (initial estimate)
 78 | 2.  **Thought 2 (User provides feedback or Cline realizes something):**
 79 |     *   `thought`: "Refining components: Data collection needs to capture user behavior (views, purchases, ratings). The engine might use collaborative filtering. Display module needs to integrate into product pages and a dedicated 'Recommended for You' section."
 80 |     *   `nextThoughtNeeded`: true
 81 |     *   `thoughtNumber`: 2
 82 |     *   `totalThoughts`: 5
 83 | 3.  **Thought 3 (Considering alternatives/constraints):**
 84 |     *   `thought`: "Constraint: Real-time vs. batch processing for recommendations. Real-time offers better UX but is more complex. Batch might be a good MVP. Let's assume batch for MVP to simplify."
 85 |     *   `nextThoughtNeeded`: true
 86 |     *   `thoughtNumber`: 3
 87 |     *   `totalThoughts`: 5
 88 | 4.  **Thought 4 (Hypothesis):**
 89 |     *   `thought`: "Hypothesis: A batch-processed collaborative filtering engine, with data collected from user interaction logs, displayed on product pages and a dedicated section, is a viable MVP architecture."
 90 |     *   `nextThoughtNeeded`: true
 91 |     *   `thoughtNumber`: 4
 92 |     *   `totalThoughts`: 5
 93 | 5.  **Thought 5 (Verification & Realization):**
 94 |     *   `thought`: "Verification: The hypothesis covers core aspects. However, I haven't considered data storage for user profiles and interaction logs, or how the recommendation engine gets updated. More thoughts needed."
 95 |     *   `nextThoughtNeeded`: true
 96 |     *   `thoughtNumber`: 5
 97 |     *   `totalThoughts`: 7 (revised estimate)
 98 |     *   `needsMoreThoughts`: true
 99 | 6.  **Thought 6 (Addressing omissions):**
100 |     *   `thought`: "Addressing data storage: A NoSQL database (e.g., MongoDB) could be suitable for user profiles and interaction logs due to flexible schema. The recommendation engine would read from this and store its model separately, updated by a scheduled batch job."
101 |     *   `nextThoughtNeeded`: true
102 |     *   `thoughtNumber`: 6
103 |     *   `totalThoughts`: 7
104 | 7.  **Thought 7 (Finalizing plan for MVP):**
105 |     *   `thought`: "Final MVP Plan: 1. User interaction logger (to NoSQL DB). 2. Batch collaborative filtering engine (reads from NoSQL, updates model). 3. API to serve recommendations. 4. UI integration on product pages & dedicated section. This seems complete for an MVP."
106 |     *   `nextThoughtNeeded`: false
107 |     *   `thoughtNumber`: 7
108 |     *   `totalThoughts`: 7
109 | 
110 | ## 6. Critical Reminders for Cline
111 | 
112 | *   **DO NOT** use this tool for simple, single-step tasks. It is for complex reasoning.
113 | *   **ALWAYS** ensure `thoughtNumber` increments correctly.
114 | *   **BE PREPARED** to adjust `totalThoughts` as understanding evolves.
115 | *   **FOCUS** on making progress towards a solution with each thought.
116 | *   If a line of thinking becomes a dead end, **EXPLICITLY** state this in a `thought` and consider revising a previous thought or starting a new branch.
117 | 
118 | This guide should help Cline leverage the `sequentialthinking` MCP tool to its full potential.
119 | 
120 | 


--------------------------------------------------------------------------------
/.clinerules/uv-python-usage-guide.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: A comprehensive guide to using UV for Python project management, covering installation, environment management, package handling, and best practices.
  3 | author: Cline
  4 | version: 1.0
  5 | tags: ["uv", "python", "package-manager", "venv", "guide"]
  6 | globs: ["**/*.py", "pyproject.toml"]
  7 | ---
  8 | 
  9 | # UV Python Project Management Guide
 10 | 
 11 | ## Table of Contents
 12 | - [Introduction](#introduction)
 13 | - [Installation](#installation)
 14 | - [Managing Python Versions](#managing-python-versions)
 15 | - [Project Management](#project-management)
 16 | - [Virtual Environment Management](#virtual-environment-management)
 17 | - [Package Management](#package-management)
 18 | - [Advanced Configuration](#advanced-configuration)
 19 | - [Development Workflows](#development-workflows)
 20 | - [Best Practices](#best-practices)
 21 | - [Security Considerations](#security-considerations)
 22 | - [Performance Optimization](#performance-optimization)
 23 | - [Troubleshooting](#troubleshooting)
 24 | - [Environment Variables](#environment-variables)
 25 | - [Tool Integration](#tool-integration)
 26 | - [Common Commands Reference](#common-commands-reference)
 27 | 
 28 | ## Introduction
 29 | 
 30 | UV is a modern Python package manager and virtual environment tool that offers significant performance improvements over traditional tools like pip and venv. This guide covers how to effectively use UV for Python project management.
 31 | 
 32 | ## Installation
 33 | 
 34 | ### macOS
 35 | ```bash
 36 | # Using Homebrew
 37 | brew install uv
 38 | 
 39 | # Using the installer script
 40 | curl -LsSf https://astral.sh/uv/install.sh | sh
 41 | ```
 42 | 
 43 | ### Linux
 44 | ```bash
 45 | # Using the installer script
 46 | curl -LsSf https://astral.sh/uv/install.sh | sh
 47 | ```
 48 | 
 49 | ### Windows
 50 | ```powershell
 51 | # Using winget
 52 | winget install --id=astral-sh.uv -e
 53 | 
 54 | # Using scoop
 55 | scoop install main/uv
 56 | ```
 57 | 
 58 | ## Managing Python Versions
 59 | 
 60 | UV can manage Python installations for you. Here's how to work with Python versions:
 61 | 
 62 | ### Installing Python
 63 | ```bash
 64 | # Install latest Python version
 65 | uv python install
 66 | 
 67 | # Install specific Python version
 68 | uv python install 3.12
 69 | 
 70 | # Install multiple versions
 71 | uv python install 3.11 3.12
 72 | 
 73 | # Install PyPy
 74 | uv python install pypy@3.10
 75 | ```
 76 | 
 77 | ### Listing Python Versions
 78 | ```bash
 79 | # List available and installed versions
 80 | uv python list
 81 | 
 82 | # Show all versions including other platforms
 83 | uv python list --all-versions
 84 | 
 85 | # Only show installed versions
 86 | uv python list --only-installed
 87 | ```
 88 | 
 89 | ### Finding Python Executables
 90 | ```bash
 91 | # Find default Python
 92 | uv python find
 93 | 
 94 | # Find specific version
 95 | uv python find >=3.11
 96 | ```
 97 | 
 98 | ## Project Management
 99 | 
100 | UV provides robust project management capabilities through its project system.
101 | 
102 | ### Creating a New Project
103 | ```bash
104 | # Create a new project
105 | uv init my-project
106 | cd my-project
107 | 
108 | # Or initialize in current directory
109 | mkdir my-project
110 | cd my-project
111 | uv init
112 | ```
113 | 
114 | This creates:
115 | - `pyproject.toml` - Project configuration and dependencies
116 | - `.python-version` - Python version specification
117 | - `README.md` - Project documentation
118 | - `main.py` - Initial Python file
119 | 
120 | ### Project Structure
121 | ```
122 | my-project/
123 | ├── .venv/               # Virtual environment (created on first use)
124 | ├── .python-version      # Python version specification
125 | ├── pyproject.toml       # Project configuration
126 | ├── uv.lock             # Dependency lock file
127 | ├── README.md           # Project documentation
128 | └── main.py             # Main Python file
129 | ```
130 | 
131 | ### Managing Dependencies
132 | 
133 | ```bash
134 | # Add dependencies
135 | uv add requests
136 | uv add 'flask>=2.0.0'
137 | uv add 'pytest[testing]'
138 | 
139 | # Remove dependencies
140 | uv remove requests
141 | 
142 | # Update dependencies
143 | uv lock --upgrade-package requests
144 | 
145 | # Install all dependencies
146 | uv sync
147 | ```
148 | 
149 | ## Virtual Environment Management
150 | 
151 | UV automatically manages virtual environments for projects and can work with existing environments.
152 | 
153 | ### Creating Virtual Environments
154 | ```bash
155 | # Create venv in default location (.venv)
156 | uv venv
157 | 
158 | # Create venv with specific name
159 | uv venv my-env
160 | 
161 | # Create venv with specific Python version
162 | uv venv --python 3.12
163 | ```
164 | 
165 | ### Working with Virtual Environments
166 | 
167 | ```bash
168 | # Activate virtual environment
169 | # On Unix/macOS:
170 | source .venv/bin/activate
171 | 
172 | # On Windows:
173 | .venv\Scripts\activate
174 | 
175 | # On Fish shell:
176 | source .venv/bin/activate.fish
177 | 
178 | # Deactivate virtual environment
179 | deactivate
180 | ```
181 | 
182 | ### Using Existing Environments
183 | 
184 | UV automatically detects and uses virtual environments in the following order:
185 | 1. Active virtual environment (VIRTUAL_ENV)
186 | 2. Active Conda environment (CONDA_PREFIX)
187 | 3. `.venv` in current or parent directories
188 | 
189 | ## Package Management
190 | 
191 | UV provides both high-level project commands and pip-compatible commands for package management.
192 | 
193 | ### Project-Based Package Management
194 | ```bash
195 | # Add package to project
196 | uv add package-name
197 | 
198 | # Remove package from project
199 | uv remove package-name
200 | 
201 | # Sync project dependencies
202 | uv sync
203 | 
204 | # Update lockfile
205 | uv lock
206 | ```
207 | 
208 | ### Pip-Compatible Commands
209 | ```bash
210 | # Install packages
211 | uv pip install package-name
212 | uv pip install -r requirements.txt
213 | 
214 | # Install in editable mode
215 | uv pip install -e .
216 | 
217 | # Uninstall packages
218 | uv pip uninstall package-name
219 | 
220 | # List installed packages
221 | uv pip list
222 | 
223 | # Show package info
224 | uv pip show package-name
225 | 
226 | # Generate requirements.txt
227 | uv pip freeze > requirements.txt
228 | ```
229 | 
230 | ## Advanced Configuration
231 | 
232 | ### pyproject.toml Configuration
233 | ```toml
234 | [project]
235 | name = "my-project"
236 | version = "0.1.0"
237 | description = "Project description"
238 | readme = "README.md"
239 | requires-python = ">=3.8"
240 | license = { text = "MIT" }
241 | authors = [
242 |     { name = "Your Name", email = "your.email@example.com" }
243 | ]
244 | 
245 | dependencies = [
246 |     "requests>=2.28.0",
247 |     "flask[async]>=2.0.0",
248 |     "sqlalchemy",
249 | ]
250 | 
251 | [project.optional-dependencies]
252 | test = ["pytest>=7.0", "pytest-cov"]
253 | dev = ["black", "mypy", "ruff"]
254 | 
255 | [tool.uv]
256 | python-version = "3.12"
257 | ```
258 | 
259 | ### UV Configuration Options
260 | ```toml
261 | [tool.uv]
262 | # Package index configuration
263 | [[tool.uv.index]]
264 | url = "https://pypi.org/simple"
265 | default = true
266 | 
267 | [[tool.uv.index]]
268 | url = "https://test.pypi.org/simple"
269 | secondary = true
270 | 
271 | # Build settings
272 | no-binary = ["cryptography", "numpy"]
273 | build-isolation = true
274 | 
275 | # Cache settings
276 | cache-dir = "~/.cache/uv"
277 | ```
278 | 
279 | ### Environment-Specific Settings
280 | ```toml
281 | [tool.uv.env]
282 | development = { extras = ["dev", "test"] }
283 | production = { extras = [] }
284 | ```
285 | 
286 | ## Development Workflows
287 | 
288 | ### Local Development Setup
289 | ```bash
290 | # Initialize new project
291 | uv init my-project
292 | cd my-project
293 | 
294 | # Set up development environment
295 | uv add --dev black ruff mypy pytest
296 | uv add --dev 'pre-commit>=3.0.0'
297 | 
298 | # Create pre-commit config
299 | cat > .pre-commit-config.yaml << EOF
300 | repos:
301 | -   repo: https://github.com/astral-sh/ruff-pre-commit
302 |     rev: v0.3.0
303 |     hooks:
304 |     -   id: ruff
305 |         args: [--fix]
306 | -   repo: https://github.com/psf/black
307 |     rev: 24.2.0
308 |     hooks:
309 |     -   id: black
310 | EOF
311 | 
312 | # Install pre-commit hooks
313 | uv run pre-commit install
314 | ```
315 | 
316 | ### CI/CD Integration
317 | ```yaml
318 | # .github/workflows/python-ci.yml
319 | name: Python CI
320 | 
321 | on: [push, pull_request]
322 | 
323 | jobs:
324 |   test:
325 |     runs-on: ubuntu-latest
326 |     steps:
327 |     - uses: actions/checkout@v4
328 |     
329 |     - name: Install UV
330 |       run: curl -LsSf https://astral.sh/uv/install.sh | sh
331 | 
332 |     - name: Setup Python
333 |       run: uv python install 3.12
334 | 
335 |     - name: Install dependencies
336 |       run: |
337 |         uv pip install -e ".[test]"
338 |         
339 |     - name: Run tests
340 |       run: uv run pytest
341 | ```
342 | 
343 | ### Working with Multiple Python Versions
344 | ```bash
345 | # Create test environments
346 | for version in 3.8 3.9 3.10 3.11 3.12; do
347 |     uv venv "venv-$version" --python "$version"
348 |     source "venv-$version/bin/activate"
349 |     uv pip install -e ".[test]"
350 |     uv run pytest
351 |     deactivate
352 | done
353 | ```
354 | 
355 | ## Best Practices
356 | 
357 | ### 1. Project Structure
358 | ```
359 | my-project/
360 | ├── .git/
361 | ├── .gitignore
362 | ├── .pre-commit-config.yaml
363 | ├── .python-version
364 | ├── .venv/
365 | ├── src/
366 | │   └── my_project/
367 | │       ├── __init__.py
368 | │       ├── core.py
369 | │       └── utils/
370 | ├── tests/
371 | │   ├── __init__.py
372 | │   └── test_core.py
373 | ├── docs/
374 | ├── pyproject.toml
375 | ├── uv.lock
376 | └── README.md
377 | ```
378 | 
379 | ### 2. Version Control Best Practices
380 | ```gitignore
381 | # .gitignore
382 | .venv/
383 | __pycache__/
384 | *.py[cod]
385 | *$py.class
386 | .pytest_cache/
387 | .coverage
388 | htmlcov/
389 | dist/
390 | build/
391 | *.egg-info/
392 | ```
393 | 
394 | ### 3. Dependency Management
395 | - Use semantic versioning for dependencies:
396 |   ```toml
397 |   dependencies = [
398 |       "requests~=2.28.0",     # Compatible releases (>=2.28.0, <2.29.0)
399 |       "flask>=2.0.0,<3.0.0",  # Specific version range
400 |       "sqlalchemy==2.0.0",    # Exact version
401 |   ]
402 |   ```
403 | 
404 | - Lock dependencies for reproducibility:
405 |   ```bash
406 |   # Update lockfile
407 |   uv lock
408 |   
409 |   # Sync environment with lockfile
410 |   uv sync
411 |   ```
412 | 
413 | ### 4. Testing and Quality Assurance
414 | ```bash
415 | # Install test dependencies
416 | uv add --dev pytest pytest-cov black mypy ruff
417 | 
418 | # Run tests with coverage
419 | uv run pytest --cov=src/my_project
420 | 
421 | # Run type checking
422 | uv run mypy src/my_project
423 | 
424 | # Run linting
425 | uv run ruff check src/my_project
426 | ```
427 | 
428 | ### 5. Documentation
429 | - Use docstrings for all public APIs
430 | - Maintain up-to-date README.md
431 | - Document environment setup requirements
432 | - Include example usage
433 | 
434 | ### 6. Security Best Practices
435 | - Keep UV and Python updated
436 | - Use UV's hash verification
437 | - Audit dependencies regularly
438 | - Use private package indexes securely
439 | 
440 | ### 7. Performance Optimization
441 | - Use UV's concurrent downloads
442 | - Leverage caching effectively
443 | - Optimize dependency resolution
444 | - Use prebuilt wheels when possible
445 | 
446 | ## Security Considerations
447 | 
448 | ### Package Verification
449 | ```bash
450 | # Enable hash verification
451 | uv pip install --require-hashes -r requirements.txt
452 | 
453 | # Generate requirements with hashes
454 | uv pip freeze --all --require-hashes > requirements.txt
455 | ```
456 | 
457 | ### Private Package Indexes
458 | ```toml
459 | [tool.uv]
460 | [[tool.uv.index]]
461 | url = "https://private.pypi.org/simple"
462 | username = "${PYPI_USERNAME}"
463 | password = "${PYPI_PASSWORD}"
464 | ```
465 | 
466 | ### Dependency Auditing
467 | ```bash
468 | # Install safety checker
469 | uv tool install safety
470 | 
471 | # Check for known vulnerabilities
472 | safety check
473 | ```
474 | 
475 | ## Performance Optimization
476 | 
477 | ### Caching Configuration
478 | ```bash
479 | # Set custom cache directory
480 | export UV_CACHE_DIR="/path/to/cache"
481 | 
482 | # Clear cache
483 | uv cache clean
484 | 
485 | # Prune old cache entries
486 | uv cache prune
487 | ```
488 | 
489 | ### Build Optimization
490 | ```bash
491 | # Set concurrent build limit
492 | export UV_CONCURRENT_BUILDS=4
493 | 
494 | # Disable build isolation for speed
495 | uv pip install --no-build-isolation package-name
496 | ```
497 | 
498 | ## Troubleshooting
499 | 
500 | ### Common Issues and Solutions
501 | 
502 | 1. **Package Installation Failures**
503 |    ```bash
504 |    # Try with --verbose for more information
505 |    uv pip install --verbose package-name
506 |    
507 |    # Force reinstall
508 |    uv pip install --force-reinstall package-name
509 |    ```
510 | 
511 | 2. **Virtual Environment Issues**
512 |    ```bash
513 |    # Recreate virtual environment
514 |    rm -rf .venv
515 |    uv venv
516 |    uv sync
517 |    ```
518 | 
519 | 3. **Dependency Conflicts**
520 |    ```bash
521 |    # Check for conflicts
522 |    uv pip check
523 |    
524 |    # Show dependency tree
525 |    uv pip tree
526 |    ```
527 | 
528 | ### Debug Mode
529 | ```bash
530 | # Enable debug logging
531 | export RUST_LOG=debug
532 | uv pip install package-name
533 | ```
534 | 
535 | ## Environment Variables
536 | 
537 | ### Common Environment Variables
538 | ```bash
539 | # Cache configuration
540 | export UV_CACHE_DIR="/path/to/cache"
541 | export UV_NO_CACHE=1
542 | 
543 | # Python configuration
544 | export UV_PYTHON_INSTALL_DIR="/path/to/pythons"
545 | export UV_PYTHON_PREFERENCE="managed"
546 | 
547 | # Network configuration
548 | export UV_HTTP_TIMEOUT=30
549 | export UV_OFFLINE=1
550 | 
551 | # Build configuration
552 | export UV_CONCURRENT_BUILDS=4
553 | export UV_NO_BUILD_ISOLATION=1
554 | ```
555 | 
556 | ## Tool Integration
557 | 
558 | ### Editor Integration (VSCode)
559 | ```json
560 | {
561 |     "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
562 |     "python.analysis.typeCheckingMode": "basic",
563 |     "python.formatting.provider": "black",
564 |     "python.linting.enabled": true,
565 |     "python.linting.lintOnSave": true
566 | }
567 | ```
568 | 
569 | ### Pre-commit Integration
570 | ```yaml
571 | # .pre-commit-config.yaml
572 | repos:
573 | -   repo: https://github.com/astral-sh/ruff-pre-commit
574 |     rev: v0.3.0
575 |     hooks:
576 |     -   id: ruff
577 |         args: [--fix]
578 | -   repo: https://github.com/psf/black
579 |     rev: 24.2.0
580 |     hooks:
581 |     -   id: black
582 | -   repo: https://github.com/pre-commit/mirrors-mypy
583 |     rev: v1.8.0
584 |     hooks:
585 |     -   id: mypy
586 |         additional_dependencies: [types-all]
587 | ```
588 | 
589 | ### Docker Integration
590 | ```dockerfile
591 | FROM python:3.12-slim
592 | 
593 | # Install UV
594 | RUN curl -LsSf https://astral.sh/uv/install.sh | sh
595 | 
596 | WORKDIR /app
597 | COPY . .
598 | 
599 | # Install dependencies
600 | RUN uv pip install -e ".[prod]"
601 | 
602 | CMD ["uv", "run", "python", "-m", "my_project"]
603 | ```
604 | 
605 | ## Advanced Package Management
606 | 
607 | ### Monorepo Support
608 | ```
609 | monorepo/
610 | ├── .git/
611 | ├── pyproject.toml      # Workspace configuration
612 | ├── project1/
613 | │   ├── pyproject.toml  # Project 1 configuration
614 | │   ├── src/
615 | │   └── tests/
616 | ├── project2/
617 | │   ├── pyproject.toml  # Project 2 configuration
618 | │   ├── src/
619 | │   └── tests/
620 | └── shared/
621 |     ├── pyproject.toml  # Shared library configuration
622 |     └── src/
623 | ```
624 | 
625 | Root pyproject.toml for monorepo:
626 | ```toml
627 | [workspace]
628 | members = [
629 |     "project1",
630 |     "project2",
631 |     "shared"
632 | ]
633 | 
634 | [tool.uv.workspace]
635 | python-version = "3.12"
636 | ```
637 | 
638 | ### Complex Dependency Scenarios
639 | 
640 | 1. **Git Dependencies with Specific References**
641 |    ```toml
642 |    dependencies = [
643 |        "mypackage @ git+https://github.com/user/repo.git@main",
644 |        "otherpackage @ git+https://github.com/user/repo.git@v1.0.0",
645 |        "debugtools @ git+ssh://git@github.com/user/repo.git@d34db33f"
646 |    ]
647 |    ```
648 | 
649 | 2. **Local Development Dependencies**
650 |    ```toml
651 |    dependencies = [
652 |        "mypackage @ file:///path/to/package",
653 |        "devtool @ file:///${PROJECT_ROOT}/tools/devtool"
654 |    ]
655 |    ```
656 | 
657 | 3. **Complex Version Constraints**
658 |    ```toml
659 |    dependencies = [
660 |        "requests>=2.28.0,<3.0.0,!=2.29.0",  # Exclude specific version
661 |        "flask~=2.0.0",                       # Compatible release
662 |        "sqlalchemy>2.0.0",                   # Greater than
663 |        "pandas==2.0.*",                      # Wildcard matching
664 |    ]
665 |    ```
666 | 
667 | ### Advanced Installation Scenarios
668 | 
669 | 1. **Installing with Extras**
670 |    ```bash
671 |    # Install multiple extras
672 |    uv add 'flask[async,dotenv]'
673 |    
674 |    # Install all extras
675 |    uv add 'flask[all]'
676 |    ```
677 | 
678 | 2. **Platform-Specific Dependencies**
679 |    ```toml
680 |    [project.dependencies]
681 |    pywin32 = { version = ">=305", markers = "sys_platform == 'win32'" }
682 |    pyobjc-framework-Cocoa = { version = ">=9.0", markers = "sys_platform == 'darwin'" }
683 |    ```
684 | 
685 | 3. **Development Dependencies with Groups**
686 |    ```toml
687 |    [project.optional-dependencies]
688 |    test = [
689 |        "pytest>=7.0",
690 |        "pytest-cov>=4.0",
691 |        "pytest-asyncio>=0.21.0"
692 |    ]
693 |    lint = [
694 |        "black>=23.0",
695 |        "ruff>=0.1.0",
696 |        "mypy>=1.0"
697 |    ]
698 |    docs = [
699 |        "sphinx>=7.0",
700 |        "sphinx-rtd-theme>=1.0"
701 |    ]
702 |    dev = [
703 |        "ipython>=8.0",
704 |        "debugpy>=1.6"
705 |    ]
706 |    ```
707 | 
708 | ### Package Publishing Workflow
709 | ```bash
710 | # Build distribution
711 | uv build
712 | 
713 | # Check distribution
714 | uv run twine check dist/*
715 | 
716 | # Upload to TestPyPI
717 | uv publish --index testpypi
718 | 
719 | # Upload to PyPI
720 | uv publish
721 | 
722 | # Upload with trusted publishing (GitHub Actions)
723 | uv publish --oidc
724 | ```
725 | 
726 | ### Advanced Cache Management
727 | ```bash
728 | # View cache information
729 | uv cache info
730 | 
731 | # Clean specific cache types
732 | uv cache clean --wheels    # Clean wheel cache
733 | uv cache clean --sources   # Clean source cache
734 | uv cache clean --http      # Clean HTTP cache
735 | 
736 | # Set cache retention period
737 | uv cache prune --older-than 30d
738 | ```
739 | 
740 | ### Custom Index Configuration
741 | ```toml
742 | [tool.uv]
743 | # Configure multiple package indexes
744 | [[tool.uv.index]]
745 | url = "https://pypi.org/simple"
746 | default = true
747 | 
748 | [[tool.uv.index]]
749 | url = "https://test.pypi.org/simple"
750 | secondary = true
751 | 
752 | [[tool.uv.index]]
753 | url = "https://private.pypi.org/simple"
754 | username = "${PYPI_USERNAME}"
755 | password = "${PYPI_PASSWORD}"
756 | 
757 | # Index-specific settings
758 | [tool.uv.index-settings]
759 | timeout = 30
760 | verify-ssl = true
761 | retries = 3
762 | ```
763 | 
764 | ## Common Commands Reference
765 | 
766 | ### Project Commands
767 | ```bash
768 | uv init              # Create new project
769 | uv add              # Add dependency
770 | uv remove           # Remove dependency
771 | uv sync             # Install dependencies
772 | uv lock             # Update lockfile
773 | uv run              # Run command in project environment
774 | ```
775 | 
776 | ### Virtual Environment Commands
777 | ```bash
778 | uv venv             # Create virtual environment
779 | uv pip install      # Install packages
780 | uv pip uninstall    # Remove packages
781 | uv pip list         # List installed packages
782 | uv pip freeze       # Generate requirements.txt
783 | ```
784 | 
785 | ### Python Management Commands
786 | ```bash
787 | uv python install   # Install Python
788 | uv python list      # List Python versions
789 | uv python find      # Find Python executable
790 | uv python pin       # Pin Python version
791 | ```
792 | 
793 | ### Tool Commands
794 | ```bash
795 | uvx                 # Run tool without installing
796 | uv tool install     # Install tool globally
797 | uv tool uninstall   # Remove tool
798 | uv tool list        # List installed tools
799 | 


--------------------------------------------------------------------------------
/.clinerules/writing-effective-clinerules.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: Guidelines and best practices for creating effective .clinerules to guide Cline's behavior, knowledge, and workflows.
  3 | author: https://github.com/nickbaumann98
  4 | version: 1.1
  5 | tags: ["meta", "guideline", "clinerules", "documentation", "best-practices"]
  6 | globs: ["clinerules/**/*.md"] # This rule is relevant when writing or editing any .clinerule
  7 | ---
  8 | 
  9 | # Writing Effective .clinerules
 10 | 
 11 | Effective `.clinerules` are the cornerstone of Cline's tailored assistance. They guide Cline's behavior, provide context, and define workflows. This document outlines best practices for creating powerful and understandable rules, ensuring they effectively direct Cline.
 12 | 
 13 | ## 1. Getting Started: The Basics
 14 | 
 15 | Refer to the main `README.md` in the `.clinerules` repository for instructions on:
 16 | * Forking the repository.
 17 | * Creating new Markdown files (`.md`) in the `clinerules/` directory.
 18 | * Naming your files using `kebab-case` (e.g., `my-new-rule.md`).
 19 | * Submitting Pull Requests.
 20 | 
 21 | ## 2. Core Principles for All ClineRules
 22 | 
 23 | * **Clear Objective:** Every rule should have a well-defined purpose. State this objective clearly at the beginning of the rule, ideally in the frontmatter `description` and reinforced in the introductory text.
 24 |     * *Example:* `cline-for-research.md` starts with an "Objective" section. This document's objective is stated in its frontmatter `description` and introduction.
 25 | * **Structured Content:** Use Markdown effectively to structure your rule.
 26 |     * **Headings and Subheadings:** Organize content logically using `#`, `##`, `###`, etc.
 27 |     * **Lists:** Use bulleted (`*`, `-`) or numbered (`1.`, `2.`) lists for steps, criteria, or key points.
 28 |     * **Code Blocks:** Use fenced code blocks (```) for code examples, commands, or structured data. Specify the language for syntax highlighting (e.g., ```typescript ... ```).
 29 |     * **Emphasis:** Use **bold** and *italics* to highlight important terms or instructions.
 30 | * **Clarity and Precision:** Write in a clear, unambiguous manner. Avoid jargon where possible, or explain it if necessary. If the rule is meant to guide AI behavior, precision is paramount.
 31 | * **Modularity:** Each rule should ideally focus on a specific topic, tool, workflow, or area of knowledge. This makes rules easier to manage, understand, and update.
 32 | 
 33 | ## 3. Frontmatter for Metadata
 34 | 
 35 | Use YAML frontmatter at the beginning of your rule file to provide metadata. This helps Cline (and humans) understand the rule's context and applicability.
 36 | 
 37 | ```yaml
 38 | ---
 39 | description: A brief explanation of what this rule is for.
 40 | author: Your Name/Handle
 41 | version: 1.0
 42 | # Globs can specify file patterns where this rule is particularly relevant.
 43 | # Cline might use this to prioritize or activate rules.
 44 | globs: ["**/*.js", "**/*.ts", "specific-config.json"]
 45 | # Tags can help categorize rules.
 46 | tags: ["coding-guideline", "documentation", "workflow", "supabase"]
 47 | ---
 48 | 
 49 | # Rule Title
 50 | ... rest of the rule content ...
 51 | ```
 52 | 
 53 | * **`description`**: A concise summary of the rule's purpose (as used in this document).
 54 | * **`globs`**: (As seen in `next-js-supabase.md` and this document) An array of file patterns indicating relevance.
 55 | * **Other metadata**: Include `author`, `version`, `tags` as appropriate (see this document's frontmatter for an example).
 56 | 
 57 | ## 4. Types of ClineRules and Their Structure
 58 | 
 59 | ClineRules can serve various purposes. Tailor the structure and content to the type of rule you're writing.
 60 | 
 61 | ### a. Informational / Documentation Rules
 62 | Provide comprehensive information about a system, architecture, or technology. This document is an example of an informational rule.
 63 | * **Key Elements:**
 64 |     * Overview and project goals.
 65 |     * Detailed explanations of components, concepts, or processes.
 66 |     * Diagrams (e.g., Mermaid.js, as seen in `cline-architecture.md`) to visualize systems.
 67 |     * Code snippets or configuration examples.
 68 |     * Definitions of key terms.
 69 | * **Example:** `cline-architecture.md`, `cline-for-slides.md`, this `writing-effective-clinesrules.md` document.
 70 | 
 71 | ### b. Process / Workflow Rules
 72 | Define a sequence of steps for Cline or the user to follow to achieve a specific outcome.
 73 | * **Key Elements:**
 74 |     * A clear start and end point.
 75 |     * Numbered steps for sequential actions.
 76 |     * Decision points with clear options (e.g., "If X, then Y, else Z").
 77 |     * Specification of tools to be used at each step (e.g., `use_mcp_tool`, `write_to_file`).
 78 |     * Expected inputs and outputs for each step.
 79 |     * Notes on dependencies or prerequisites.
 80 | * **Example:** `cline-for-research.md`, `mcp-development-protocol.md`
 81 | 
 82 | ### c. Behavioral / Instructional Rules (for Guiding AI)
 83 | These rules directly instruct Cline on how it should behave, process information, or generate responses, especially in specific contexts.
 84 | * **Key Elements:**
 85 |     * **Explicit Instructions:** Use imperative verbs (MUST, SHOULD, DO NOT, NEVER, ALWAYS).
 86 |     * **Critical Warnings:** Use formatting (bold, ALL CAPS, emojis like 🚨, ⚠️, ✅, ❌) to draw attention to critical instructions or prohibitions (as seen in `next-js-supabase.md` and `mcp-development-protocol.md`).
 87 |     * **Positive and Negative Examples:** Show correct and incorrect ways of doing things (e.g., code patterns to use vs. avoid).
 88 |     * **Triggers and Conditions:** Define when the rule or specific instructions within it should be activated.
 89 |     * **Verification Steps:** Include "thinking" blocks or checklists for the AI to verify its actions against the rule's constraints (e.g., the `<thinking>` block in `mcp-development-protocol.md`).
 90 |     * **Context Management:** Define how Cline should manage context, memory, or state if relevant (e.g., `memory-bank.md`).
 91 | * **Example:** `next-js-supabase.md`, `memory-bank.md`
 92 | 
 93 | ### d. Meta-Rules
 94 | Rules that define how Cline manages or improves its own rules or processes.
 95 | * **Key Elements:**
 96 |     * Triggers for the meta-process.
 97 |     * Steps involved in the meta-process (e.g., reflection, suggesting improvements).
 98 |     * User interaction points (e.g., asking for confirmation).
 99 | * **Example:** `self-improving-cline.md`
100 | 
101 | ## 5. Language and Formatting for AI Guidance
102 | 
103 | When writing rules intended to directly steer Cline's AI behavior, certain conventions are highly effective:
104 | 
105 | * **Be Directive:**
106 |     * Use **MUST** for absolute requirements.
107 |     * Use **SHOULD** for strong recommendations.
108 |     * Use **MAY** for optional actions.
109 |     * Use **MUST NOT** or **NEVER** for absolute prohibitions.
110 |     * Use **SHOULD NOT** for strong discouragement.
111 | * **Highlight Critical Information:**
112 |     * `next-js-supabase.md` uses "🚨 CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS 🚨" and "❌ NEVER GENERATE THIS CODE" / "✅ ALWAYS GENERATE THIS EXACT PATTERN".
113 |     * `mcp-development-protocol.md` uses "⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️" and "BLOCKER ⛔️".
114 | * **Provide Concrete Examples:**
115 |     * Show exact code snippets, commands, or output formats.
116 |     * For code generation, clearly distinguish between desired and undesired patterns.
117 | * **Define AI's "Thought Process":**
118 |     * The `<thinking> ... </thinking>` block in `mcp-development-protocol.md` is a good way to make the AI "pause and check" its understanding or state before proceeding.
119 |     * The "AI MODEL VERIFICATION STEPS" in `next-js-supabase.md` serve a similar purpose.
120 | * **Specify Tool Usage:**
121 |     * If Cline needs to use a specific tool (e.g., `attempt_completion`, `replace_in_file`, `use_mcp_tool`), explicitly state it and provide any necessary parameters or context for that tool.
122 | 
123 | ## 6. Content Best Practices
124 | 
125 | * **Start Broad, Then Narrow:** Begin with a general overview or objective, then delve into specifics.
126 | * **Use Analogies or Scenarios:** If explaining a complex concept, an analogy or a use-case scenario can be helpful.
127 | * **Define Terminology:** If your rule introduces specific terms or acronyms, define them.
128 | * **Anticipate Questions:** Try to think about what questions a user (or Cline itself) might have and address them proactively.
129 | * **Keep it Updated:** As systems or processes change, ensure the relevant `.clinerules` are updated to reflect those changes. The `self-improving-cline.md` rule encourages this.
130 | 
131 | ## 7. Referencing Other Rules
132 | 
133 | If your rule builds upon or relates to another rule, feel free to reference it by its filename. This helps create a connected knowledge base.
134 | 
135 | ## 8. Testing Your Rule
136 | 
137 | While not always formally testable, consider how your rule will be interpreted:
138 | * **Human Readability:** Is it clear to another person? If so, it's more likely to be clear to Cline.
139 | * **AI Interpretation (for behavioral rules):** Does it provide enough specific guidance? Are there ambiguities? Try "role-playing" as Cline and see if you can follow the instructions.
140 | * **Practical Application:** If it's a workflow, manually step through it. If it's a coding guideline, try applying it to a piece of code.
141 | * **Self-Review Against These Guidelines:** Does your new rule adhere to the principles and best practices outlined in *this very document* (`writing-effective-clinesrules.md`)?
142 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Cline Community Prompts
 2 | 
 3 | This repository serves as a community-driven collection of .clinerules & workflows for Cline.
 4 | 
 5 | ## Contributing
 6 | 
 7 | We welcome contributions!
 8 | 
 9 | ### Contributing Rules
10 | 
11 | To add your own Cline rule:
12 | 
13 | 1.  **Fork** this repository.
14 | 2.  **Create** a new Markdown file (`.md`) for your rule inside the `.clinerules/` directory.
15 | 3.  **Name** your file using `kebab-case` (e.g., `my-awesome-rule.md`).
16 | 4.  **Add** the content of your rule to the file.
17 | 5.  **Commit** your changes and push them to your fork.
18 | 6.  **Submit** a Pull Request (PR) to the main repository.
19 | 
20 | Your contribution will be reviewed, and once approved, it will be merged into the [collection](https://cline.bot/prompts).
21 | 
22 | ### Contributing Workflows
23 | 
24 | To add your own Cline workflow:
25 | 
26 | 1.  **Fork** this repository.
27 | 2.  **Create** a new Markdown file (`.md`) for your workflow inside the `workflows/` directory.
28 | 3.  **Name** your file using `kebab-case` (e.g., `my-awesome-workflow.md`).
29 | 4.  **Add** the content of your workflow to the file.
30 | 5.  **Commit** your changes and push them to your fork.
31 | 6.  **Submit** a Pull Request (PR) to the main repository.
32 | 
33 | Your contribution will be reviewed, and once approved, it will be merged into the [collection](https://cline.bot/prompts).
34 | 


--------------------------------------------------------------------------------
/workflows/pr-review-cline.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | description: "A detailed workflow for Cline (the AI assistant) to review Pull Requests specifically for the Cline project, utilizing the gh CLI and internal knowledge."
  3 | author: "Cline Team"
  4 | version: "1.0"
  5 | tags: ["pr review", "github", "cline project", "ai workflow", "gh cli"]
  6 | globs: ["*.*"]
  7 | ---
  8 | You have access to the `gh` terminal command. I already authenticated it for you. Please review it to use the PR that I asked you to review. You're already in the `cline` repo.
  9 | 
 10 | <detailed_sequence_of_steps>
 11 | 
 12 | # GitHub PR Review Process - Detailed Sequence of Steps
 13 | 
 14 | ## 1. Gather PR Information
 15 | 
 16 | 1. Get the PR title, description, and comments:
 17 | 
 18 |     ```bash
 19 |     gh pr view <PR-number> --json title,body,comments
 20 |     ```
 21 | 
 22 | 2. Get the full diff of the PR:
 23 |     ```bash
 24 |     gh pr diff <PR-number>
 25 |     ```
 26 | 
 27 | ## 2. Understand the Context
 28 | 
 29 | 1. Identify which files were modified in the PR:
 30 | 
 31 |     ```bash
 32 |     gh pr view <PR-number> --json files
 33 |     ```
 34 | 
 35 | 2. Examine the original files in the main branch to understand the context:
 36 | 
 37 |     ```xml
 38 |     <read_file>
 39 |     <path>path/to/file</path>
 40 |     </read_file>
 41 |     ```
 42 | 
 43 | 3. For specific sections of a file, you can use search_files:
 44 |     ```xml
 45 |     <search_files>
 46 |     <path>path/to/directory</path>
 47 |     <regex>search term</regex>
 48 |     <file_pattern>*.ts</file_pattern>
 49 |     </search_files>
 50 |     ```
 51 | 
 52 | ## 3. Analyze the Changes
 53 | 
 54 | 1. For each modified file, understand:
 55 | 
 56 |     - What was changed
 57 |     - Why it was changed (based on PR description)
 58 |     - How it affects the codebase
 59 |     - Potential side effects
 60 | 
 61 | 2. Look for:
 62 |     - Code quality issues
 63 |     - Potential bugs
 64 |     - Performance implications
 65 |     - Security concerns
 66 |     - Test coverage
 67 | 
 68 | ## 4. Ask for User Confirmation
 69 | 
 70 | 1. Before making a decision, ask the user if you should approve the PR, providing your assessment and justification:
 71 | 
 72 |     ```xml
 73 |     <ask_followup_question>
 74 |     <question>Based on my review of PR #<PR-number>, I recommend [approving/requesting changes]. Here's my justification:
 75 | 
 76 |     [Detailed justification with key points about the PR quality, implementation, and any concerns]
 77 | 
 78 |     Would you like me to proceed with this recommendation?</question>
 79 |     <options>["Yes, approve the PR", "Yes, request changes", "No, I'd like to discuss further"]</options>
 80 |     </ask_followup_question>
 81 |     ```
 82 | 
 83 | ## 5. Ask if User Wants a Comment Drafted
 84 | 
 85 | 1. After the user decides on approval/rejection, ask if they would like a comment drafted:
 86 | 
 87 |     ```xml
 88 |     <ask_followup_question>
 89 |     <question>Would you like me to draft a comment for this PR that you can copy and paste?</question>
 90 |     <options>["Yes, please draft a comment", "No, I'll handle the comment myself"]</options>
 91 |     </ask_followup_question>
 92 |     ```
 93 | 
 94 | 2. If the user wants a comment drafted, provide a well-structured comment they can copy:
 95 | 
 96 |     ```
 97 |     Thank you for this PR! Here's my assessment:
 98 | 
 99 |     [Detailed assessment with key points about the PR quality, implementation, and any suggestions]
100 | 
101 |     [Include specific feedback on code quality, functionality, and testing]
102 |     ```
103 | 
104 | ## 6. Make a Decision
105 | 
106 | 1. Approve the PR if it meets quality standards:
107 | 
108 |     ```bash
109 |     # For single-line comments:
110 |     gh pr review <PR-number> --approve --body "Your approval message"
111 | 
112 |     # For multi-line comments with proper whitespace formatting:
113 |     cat << EOF | gh pr review <PR-number> --approve --body-file -
114 |     Thanks @username for this PR! The implementation looks good.
115 | 
116 |     I particularly like how you've handled X and Y.
117 | 
118 |     Great work!
119 |     EOF
120 |     ```
121 | 
122 | 2. Request changes if improvements are needed:
123 | 
124 |     ```bash
125 |     # For single-line comments:
126 |     gh pr review <PR-number> --request-changes --body "Your feedback message"
127 | 
128 |     # For multi-line comments with proper whitespace formatting:
129 |     cat << EOF | gh pr review <PR-number> --request-changes --body-file -
130 |     Thanks @username for this PR!
131 | 
132 |     The implementation looks promising, but there are a few things to address:
133 | 
134 |     1. Issue one
135 |     2. Issue two
136 | 
137 |     Please make these changes and we can merge this.
138 |     EOF
139 |     ```
140 | 
141 |     Note: The `cat << EOF | ... --body-file -` approach preserves all whitespace and formatting without requiring temporary files. The `-` parameter tells the command to read from standard input.
142 |     </detailed_sequence_of_steps>
143 | 
144 | <example_review_process>
145 | 
146 | # Example PR Review Process
147 | 
148 | Let's walk through a real example of reviewing PR #3627 which fixes the thinking mode calculation for Claude 3.7 models.
149 | 
150 | ## Step 1: Gather PR Information
151 | 
152 | ```bash
153 | # Get PR details
154 | gh pr view 3627 --json title,body,comments
155 | 
156 | # Get the full diff
157 | gh pr diff 3627
158 | ```
159 | 
160 | ## Step 2: Understand the Context
161 | 
162 | ```xml
163 | # Examine the original files to understand what's being changed
164 | <read_file>
165 | <path>src/shared/api.ts</path>
166 | </read_file>
167 | 
168 | # Look at the ThinkingBudgetSlider component implementation
169 | <read_file>
170 | <path>webview-ui/src/components/settings/ThinkingBudgetSlider.tsx</path>
171 | </read_file>
172 | 
173 | # Check how thinking mode is currently handled in API providers
174 | <search_files>
175 | <path>src/api/providers</path>
176 | <regex>reasoningOn</regex>
177 | <file_pattern>*.ts</file_pattern>
178 | </search_files>
179 | ```
180 | 
181 | ## Step 3: Analyze the Changes
182 | 
183 | From the PR information and code examination, we can see that:
184 | 
185 | 1. The PR fixes an issue with the thinking mode budget calculation for Claude 3.7 models
186 | 2. Currently, the thinking budget is incorrectly calculated as 80% of maxTokens (8192), resulting in 6553 tokens
187 | 3. Claude 3.7 actually supports a much larger thinking budget (up to 64000 tokens)
188 | 4. The PR adds a `thinkingConfig` property with `maxBudget: 64000` to model definitions
189 | 5. It updates API handlers to use this value when reasoning mode is enabled
190 | 6. It enhances the slider component to calculate max values based on model-specific percentages
191 | 7. Comprehensive tests were added to verify the calculations
192 | 
193 | ## Step 4: Ask for User Confirmation
194 | 
195 | ```xml
196 | <ask_followup_question>
197 | <question>Based on my review of PR #3627, I recommend approving this PR. Here's my justification:
198 | 
199 | 1. The PR correctly fixes the thinking mode budget calculation for Claude 3.7 models
200 | 2. It properly implements the thinkingConfig.maxBudget property (64000) for Claude 3.7 models
201 | 3. It applies the appropriate percentage (50%) for the slider calculation
202 | 4. The changes are well-tested with comprehensive unit tests
203 | 5. The implementation is clean and follows the project's coding standards
204 | 6. The PR includes helpful screenshots demonstrating the fix
205 | 
206 | Would you like me to proceed with approving this PR?</question>
207 | <options>["Yes, approve the PR", "No, I'd like to discuss further", "Let me review it myself first"]</options>
208 | </ask_followup_question>
209 | ```
210 | 
211 | ## Step 5: Ask if User Wants a Comment Drafted
212 | 
213 | ```xml
214 | <ask_followup_question>
215 | <question>Would you like me to draft a comment for this PR that you can copy and paste?</question>
216 | <options>["Yes, please draft a comment", "No, I'll handle the comment myself"]</options>
217 | </ask_followup_question>
218 | ```
219 | 
220 | ## Step 6: Make a Decision
221 | 
222 | ```bash
223 | # Option 1: Simple one-line comment
224 | gh pr review 3627 --approve --body "This PR looks good! It correctly fixes the thinking mode budget calculation for Claude 3.7 models."
225 | 
226 | # Option 2: Multi-line comment with proper whitespace formatting
227 | cat << EOF | gh pr review 3627 --approve --body-file -
228 | This PR looks good! It correctly fixes the thinking mode budget calculation for Claude 3.7 models.
229 | 
230 | I particularly like:
231 | 1. The proper implementation of thinkingConfig.maxBudget property (64000)
232 | 2. The appropriate percentage (50%) for the slider calculation
233 | 3. The comprehensive unit tests
234 | 4. The clean implementation that follows project coding standards
235 | 
236 | Great work!
237 | EOF
238 | ```
239 | 
240 | </example_review_process>
241 | 
242 | <common_gh_commands>
243 | 
244 | # Common GitHub CLI Commands for PR Review
245 | 
246 | ## Basic PR Commands
247 | 
248 | ```bash
249 | # List open PRs
250 | gh pr list
251 | 
252 | # View a specific PR
253 | gh pr view <PR-number>
254 | 
255 | # View PR with specific fields
256 | gh pr view <PR-number> --json title,body,comments,files,commits
257 | 
258 | # Check PR status
259 | gh pr status
260 | ```
261 | 
262 | ## Diff and File Commands
263 | 
264 | ```bash
265 | # Get the full diff of a PR
266 | gh pr diff <PR-number>
267 | 
268 | # List files changed in a PR
269 | gh pr view <PR-number> --json files
270 | 
271 | # Check out a PR locally
272 | gh pr checkout <PR-number>
273 | ```
274 | 
275 | ## Review Commands
276 | 
277 | ```bash
278 | # Approve a PR (single-line comment)
279 | gh pr review <PR-number> --approve --body "Your approval message"
280 | 
281 | # Approve a PR (multi-line comment with proper whitespace)
282 | cat << EOF | gh pr review <PR-number> --approve --body-file -
283 | Your multi-line
284 | approval message with
285 | 
286 | proper whitespace formatting
287 | EOF
288 | 
289 | # Request changes on a PR (single-line comment)
290 | gh pr review <PR-number> --request-changes --body "Your feedback message"
291 | 
292 | # Request changes on a PR (multi-line comment with proper whitespace)
293 | cat << EOF | gh pr review <PR-number> --request-changes --body-file -
294 | Your multi-line
295 | change request with
296 | 
297 | proper whitespace formatting
298 | EOF
299 | 
300 | # Add a comment review (without approval/rejection)
301 | gh pr review <PR-number> --comment --body "Your comment message"
302 | 
303 | # Add a comment review with proper whitespace
304 | cat << EOF | gh pr review <PR-number> --comment --body-file -
305 | Your multi-line
306 | comment with
307 | 
308 | proper whitespace formatting
309 | EOF
310 | ```
311 | 
312 | ## Additional Commands
313 | 
314 | ```bash
315 | # View PR checks status
316 | gh pr checks <PR-number>
317 | 
318 | # View PR commits
319 | gh pr view <PR-number> --json commits
320 | 
321 | # Merge a PR (if you have permission)
322 | gh pr merge <PR-number> --merge
323 | ```
324 | 
325 | </common_gh_commands>
326 | 
327 | <general_guidelines_for_commenting>
328 | When reviewing a PR, please talk normally and like a friendly reviwer. You should keep it short, and start out by thanking the author of the pr and @ mentioning them.
329 | 
330 | Whether or not you approve the PR, you should then give a quick summary of the changes without being too verbose or definitive, staying humble like that this is your understanding of the changes. Kind of how I'm talking to you right now.
331 | 
332 | If you have any suggestions, or things that need to be changed, request changes instead of approving the PR.
333 | 
334 | Leaving inline comments in code is good, but only do so if you have something specific to say about the code. And make sure you leave those comments first, and then request changes in the PR with a short comment explaining the overall theme of what you're asking them to change.
335 | </general_guidelines_for_commenting>
336 | 
337 | <example_comments_that_i_have_written_before>
338 | <brief_approve_comment>
339 | Looks good, though we should make this generic for all providers & models at some point
340 | </brief_approve_comment>
341 | <brief_approve_comment>
342 | Will this work for models that may not match across OR/Gemini? Like the thinking models?
343 | </brief_approve_comment>
344 | <approve_comment>
345 | This looks great! I like how you've handled the global endpoint support - adding it to the ModelInfo interface makes total sense since it's just another capability flag, similar to how we handle other model features.
346 | 
347 | The filtered model list approach is clean and will be easier to maintain than hardcoding which models work with global endpoints. And bumping the genai library was obviously needed for this to work.
348 | 
349 | Thanks for adding the docs about the limitations too - good for users to know they can't use context caches with global endpoints but might get fewer 429 errors.
350 | </approve_comment>
351 | <requesst_changes_comment>
352 | This is awesome. Thanks @scottsus.
353 | 
354 | My main concern though - does this work for all the possible VS Code themes? We struggled with this initially which is why it's not super styled currently. Please test and share screenshots with the different themes to make sure before we can merge
355 | </request_changes_comment>
356 | <request_changes_comment>
357 | Hey, the PR looks good overall but I'm concerned about removing those timeouts. Those were probably there for a reason - VSCode's UI can be finicky with timing.
358 | 
359 | Could you add back the timeouts after focusing the sidebar? Something like:
360 | 
361 | ```typescript
362 | await vscode.commands.executeCommand("claude-dev.SidebarProvider.focus")
363 | await setTimeoutPromise(100) // Give UI time to update
364 | visibleWebview = WebviewProvider.getSidebarInstance()
365 | ```
366 | 
367 | </request_changes_comment>
368 | <request_changes_comment>
369 | Heya @alejandropta thanks for working on this!
370 | 
371 | A few notes:
372 | 1 - Adding additional info to the environment variables is fairly problematic because env variables get appended to **every single message**. I don't think this is justifiable for a somewhat niche use case.
373 | 2 - Adding this option to settings to include that could be an option, but we want our options to be simple and straightforward for new users
374 | 3 - We're working on revisualizing the way our settings page is displayed/organized, and this could potentially be reconciled once that is in and our settings page is more clearly delineated.
375 | 
376 | So until the settings page is update, and this is added to settings in a way that's clean and doesn't confuse new users, I don't think we can merge this. Please bear with us.
377 | </request_changes_comment>
378 | <request_changes_comment>
379 | Also, don't forget to add a changeset since this fixes a user-facing bug.
380 | 
381 | The architectural change is solid - moving the focus logic to the command handlers makes sense. Just don't want to introduce subtle timing issues by removing those timeouts.
382 | </request_changes_comment>
383 | </example_comments_that_i_have_written_before>
384 | 


--------------------------------------------------------------------------------