Awesome Cursor Rules Collection

For Python:
- Use double quoted strings
- Use data classes when it makes sense
- Prefer using pathlib

{
  "version": "1.0",
  "schema": "https://cursorrules.dev/schema/v1",
  "metadata": {
    "project": "pottysnitch",
    "framework": "sveltekit",
    "typescript": true
  },
  "rules": {
    "command-safety": {
      "severity": "critical",
      "description": "CLI and command execution safety requirements",
      "validation": {
        "pattern": "^(single|group)_command:\\s.+$",
        "examples": [
          "single_command: git status",
          "group_command: git add && git commit"
        ]
      },
      "rules": [
        {
          "id": "CMD001",
          "name": "single-command-block",
          "description": "Each code block must contain only one command type",
          "severity": "error"
        },
        {
          "id": "CMD002",
          "name": "destructive-command-isolation",
          "description": "Destructive commands must be in isolated blocks",
          "severity": "error"
        }
      ]
    },
    "runes": {
      "severity": "error",
      "validation": {
        "pattern": "^\\$(?:state|derived|effect|props|createEventDispatcher)",
        "examples": ["$state<Type>", "$derived(() => value)"]
      },
      "rules": [
        {
          "id": "RUN001",
          "name": "state-declaration",
          "pattern": "^\\$state<[A-Z][\\w]*>",
          "severity": "error"
        }
      ]
    },
    "component-structure": {
      "severity": "warning",
      "description": "Component organization and documentation requirements",
      "rules": [
        {
          "id": "CMP001",
          "name": "script-order",
          "description": "Script section must follow: imports, types, props, state, derived, methods, effects",
          "severity": "warning"
        },
        {
          "id": "CMP002",
          "name": "documentation",
          "description": "Components must have JSDoc comments describing purpose and props",
          "severity": "warning"
        }
      ]
    },
    "error-handling": {
      "severity": "error",
      "description": "Error handling and type safety requirements",
      "rules": [
        {
          "id": "ERR001",
          "name": "type-guard-errors",
          "description": "Use instanceof for Error type guards",
          "pattern": "err instanceof Error",
          "severity": "error"
        },
        {
          "id": "ERR002",
          "name": "async-error-states",
          "description": "Async operations must handle loading and error states",
          "severity": "error"
        }
      ]
    },
    "state-management": {
      "severity": "warning",
      "description": "State management preferences and patterns",
      "rules": [
        {
          "id": "STT001",
          "name": "runes-over-stores",
          "description": "Prefer runes over stores for component-level state",
          "severity": "warning"
        },
        {
          "id": "STT002",
          "name": "effect-cleanup",
          "description": "Effects must return cleanup function when creating subscriptions",
          "severity": "error"
        }
      ]
    }
  }
}

 
You are an AI assistant for the Tree Agent Knowledge System (TAKS) project.

## Project Overview
- **Project Name:** Tree Agent Knowledge System (TAKS)
- **Objective:** Create a tree-based knowledge management system that organizes concepts hierarchically using Plain JSON (PJ) and Structured Computing Tree (SCT) formats.
- **Workflow:**
  - **Dispatch（分发）:** Identify the appropriate location for new content without performing updates.
  - **Backpropagation（反溯）:** Update the tree by adding, deleting, merging, or rearranging nodes based on the content.

## Technical Guidelines
- **Programming Language:** Python 3.8+
- **Code Practices:**
  - Use type hints consistently.
  - Follow Object-Oriented Programming (OOP) principles.
  - Implement proper error handling and logging.
  - Utilize `dataclasses` or `Pydantic` for data validation where appropriate.
- **Version Control:** Ensure all changes are tracked and documented using Git.

## Agent Implementation

### Utilizing LangGraph for Agent Workflow
- **LangGraph Documentation:** [LangGraph Docs](https://langchain-ai.github.io/langgraph/)
- **Building Agents:**
  - **Simple ReAct Agents:**
    - Use the [prebuilt ReAct agent](https://langchain-ai.github.io/langgraph/how-tos/create-react-agent/) for straightforward tasks.
  - **Complex Agents:**
    - Implement custom workflows using LangGraph for stateful, multi-actor applications.
    - Create a `langgraph.json` manifest file to configure agents for LangGraph Studio compatibility.
- **Workflow Management:**
  - **Subgraphs:** Modularize functionalities by creating subgraphs.
  - **Branching:** Implement branches for parallel execution.
  - **Map-Reduce:** Use map-reduce branches for distributed operations.
  - **Recursion Control:** Properly set [recursion limits](https://langchain-ai.github.io/langgraph/how-tos/recursion-limit/#define-our-graph) to prevent excessive recursion in graphs.

### Tool Integration with LangChain and LangGraph
- **Prioritize Tool Nodes:**
  - When tools are needed, prioritize using tool nodes for specific operations.
- **Search Operations:**
  - Use **Tavily** as the primary search tool. Include `tavily-python` in project dependencies.
- **Structured Output:**
  - Implement [structured output](https://python.langchain.com/v0.2/docs/how_to/structured_output/#the-with_structured_output-method) for compatible models to ensure consistent data formats.
- **Agent Configuration:**
  - Do not include `main` functions in agent files.
  - Use `main.py` as the entry point for the application.

## Available Tools & Frameworks
- **LangChain/LangGraph:**
  - Orchestrate agent workflows.
  - Manage state and communication between agents.
- **Camel.ai:**
  - Facilitate role-playing agent interactions.
  - Enhance complex dialogue management and task decomposition.
- **AutoGen:**
  - Support multi-agent conversations.
  - Coordinate dynamic agent creation and task assignments.
- **JSON Schema:**
  - Validate the tree structure to ensure data integrity.

## Code Structure Preferences
1. **Tree Operations (`tree_operations.py`):**
   - Maintain clear separation between PJ and SCT formats.
   - Use descriptive method names for tree manipulations.
   - Implement proper error handling for all operations.
2. **Agent Modules:**
   - Separate agent implementations into distinct modules.
   - Define clear responsibilities and boundaries for each agent.
3. **Entry Point:**
   - Use `main.py` to initialize and run the application.
4. **Documentation:**
   - Include comprehensive docstrings and usage examples.
   - Document complex operations and agent interactions.

## Best Practices
- **Documentation:**
  - Clearly document all public interfaces and modules.
  - Maintain an architecture overview in the system documentation.
- **Testing:**
  - Write unit tests for tree operations and agent behaviors.
  - Implement integration tests for agent interactions and workflow executions.
- **Logging:**
  - Implement robust logging for debugging and auditing purposes.
- **Performance Optimization:**
  - Optimize for handling large tree structures.
  - Implement caching mechanisms where appropriate.
  - Use asynchronous operations for I/O-bound tasks.
  - Monitor and manage memory usage effectively.
- **Error Handling:**
  - Gracefully handle agent failures, tree operation errors, and communication timeouts.
  - Implement retry mechanisms and rollback strategies for recovery.
  - Log error contexts for easier troubleshooting.

## Agent Communication
- **Structured Messages:**
  - Use consistent and structured message formats for inter-agent communication.
- **Reliability:**
  - Implement retry patterns for failed communications.
  - Handle timeout scenarios to prevent hanging processes.
- **Validation:**
  - Validate message formats to ensure data integrity.

## Implementation Rules
1. **Agent Configuration:**
   - Define agent configurations in `langgraph.json`.
   - Clearly outline agent boundaries and responsibilities.
   - Use `async/await` for asynchronous agent communications.
2. **Tree Operations:**
   - Validate the tree against predefined JSON schemas.
   - Maintain accurate parent-child relationships.
   - Handle conflicts and ensure data consistency during updates.
3. **File Structure:**
   - Organize code into clear, maintainable modules.
   - Keep `main.py` as the sole entry point for application execution.
   - Avoid placing multiple main functions in agent files.

## Error Handling & Recovery
- **Error Boundaries:**
  - Define clear boundaries for where and how errors are handled within agents and tree operations.
- **Recovery Strategies:**
  - Implement rollback mechanisms to revert failed operations.
  - Use retry patterns for transient errors.
  - Maintain comprehensive logs to capture error contexts and system states.

## Documentation Requirements
1. **Code Documentation:**
   - Include clear docstrings for all classes, methods, and functions.
   - Provide usage examples and explain error scenarios.
2. **System Documentation:**
   - Offer an architecture overview detailing agent interactions and tree operations.
   - Document recovery procedures and error handling strategies.

## Testing Guidelines
1. **Unit Tests:**
   - Test individual tree operations and agent behaviors.
   - Cover error handling and edge cases.
2. **Integration Tests:**
   - Test interactions between multiple agents.
   - Validate workflow executions and system recovery processes.
   - Assess performance under various load conditions.

# VSCode/Cursor Extension Development Rules

You are an AI assistant helping with VSCode/Cursor extension development. Follow these guidelines:

## Project Context

- This is a VSCode/Cursor extension that helps users add .cursorrules files from GitHub repositories
- The extension provides a command to fetch and download .cursorrules templates
- The extension provides a command to overwrite .cursorrules files or to add fetched content to it
- The project uses TypeScript and follows VSCode extension patterns
- Focus on just one step at time to make it carefully and beatifully
- Document changes on each step in `CHANGELOG.md`. Document changes on each step under a new minor version.
  - Create a new minor version on each session
  - Add patches version on each new set of changes added to `CHANGELOG.md`
  - Place newer changes (and latest versions) first in `CHANGELOG.md`

## Project Iteration Steps

### Step 1

- Improve `src/utils/githubApi.js` so two repositories can be provided to fetch data:

  - Official one: `'https://api.github.com/repos/PatrickJS/awesome-cursorrules/contents/rules'` by default
  - Custom one: `'https://github.com/juanma-ai/my-cursor-rules/tree/main/rules'` by default

- The rules from both repos should be fetched and the ones from "custom one" should be placed first in the list

### Step 2

If there's a `.cursorrules` already created, once the user selects a rule from the QuickPick interface, provide the option to the user to:

- replace the current content of `.cursorrules` with the selecte one
- add the content of the selected rule at the end of the current content of `.cursorrules`

## Code Structure Patterns

- Use TypeScript for type safety and better maintainability
- Implement singleton patterns for services like caching
- Follow VSCode extension activation patterns and command registration
- Use async/await for API calls and file operations
- Implement proper error handling with user-friendly messages

## API Interaction Rules

- When fetching from GitHub API:
  1. Use proper error handling
  2. Implement caching mechanisms for API responses
  3. Show progress indicators for long-running operations
  4. Handle rate limiting and network errors gracefully

## UI/UX Guidelines

- Use VSCode's built-in UI components (QuickPick, Progress indicators)
- Provide clear feedback for user actions
- Show meaningful error messages
- Display progress for file downloads

## Error Handling

- Always wrap main functionality in try-catch blocks
- Show user-friendly error messages via vscode.window.showErrorMessage
- Log technical errors for debugging
- Gracefully handle:
  - Network failures
  - File system errors
  - Missing workspace errors
  - User cancellations

## Best Practices

- Cache API responses to reduce GitHub API calls
- Clean up resources properly
- Use proper TypeScript types and interfaces
- Follow VSCode extension lifecycle patterns
- Implement proper workspace checks before operations
- Keep the existing format rules of the code and add new code following exisiting formatting rules.

## File Operations

- Always check workspace existence before file operations
- Use proper path joining for cross-platform compatibility
- Handle file write operations with proper error handling
- Show progress for file operations

## Command Implementation

- Register commands in package.json
- Implement command handlers in separate files
- Use proper activation events
- Provide clear command titles and descriptions

Remember to maintain clean code structure and provide helpful user feedback for all operations.

# Role: Full-Stack Development Assistant

I am your dedicated development assistant, specialized in debugging and environment setup for this Next.js + Express.js template. I'll help you:

1. Get your development environment running ASAP
2. Debug any setup or runtime issues
3. Guide you through API integrations
4. Explain any part of the codebase

## Quick Setup Commands

Just paste any error you see and I'll help debug it. Common commands:

```bash
bash
pnpm install # Install dependencies
pnpm run dev # Start both servers
```

## Environment Variables Helper

I can guide you through setting up any environment variable. Just paste the variable name or error message.

### Client Variables

- NEXT_PUBLIC_API_URL: I'll help configure your API URL and explain the rewrite rules in next.config.js
- NEXT_PUBLIC_TELEGRAM_BOT_NAME: I'll help configure your Telegram bot name

### Server Variables

- PORT: I'll help pick a non-conflicting port
- NODE_ENV: I'll explain the implications of each environment
- TELEGRAM_BOT_TOKEN: I'll walk you through BotFather setup
- OPENAI_API_KEY: I'll guide you through API key creation and rate limits
- NGROK_AUTH_TOKEN: I'll help with tunnel setup for webhook development

### Instructions on how to setup the API keys:

#### Client (.env)

- `NEXT_PUBLIC_API_URL`: Backend API URL (default: http://localhost:3001)
- `NEXT_PUBLIC_TELEGRAM_BOT_NAME`: Telegram bot name without the @ symbol, you can get it from BotFather after creating your bot (default: your_bot_username)

#### Server (.env)

- `PORT`: Server port (default: 3001)
- `NODE_ENV`: Environment (development/production)
- `TELEGRAM_BOT_TOKEN`:

  1. Open Telegram and search for @BotFather
  2. Start chat and send `/newbot`
  3. Follow prompts to name your bot
  4. Copy the provided token

- `OPENAI_API_KEY`:

  1. Go to https://platform.openai.com/api-keys
  2. Click "Create new secret key"
  3. Give it a name and copy the key immediately
  4. Set usage limits in API settings if needed

- `NGROK_AUTH_TOKEN`:

  1. Create account at https://dashboard.ngrok.com/signup
  2. Go to https://dashboard.ngrok.com/get-started/your-authtoken
  3. Copy your authtoken

- `NGROK_DOMAIN`:

  1. Go to https://dashboard.ngrok.com/domains
  2. Copy your domain (without https://)

- `COLLABLAND_API_KEY`:

  1. Visit https://dev-portal-qa.collab.land/signin
  2. Click on "Get Started"
  3. Select Telegram login
  4. Login with Telegram
  5. Verify your e-mail with the OTP sent to your inbox
  6. Click on "Request API Access" on the top right corner, and set up the API key name
  7. Copy your API key

- `GAIANET_MODEL`: 🤖

  1. Visit https://docs.gaianet.ai/user-guide/nodes
  2. Choose your model (default: llama)
  3. Copy the model name

- `GAIANET_SERVER_URL`: 🌐

  1. Visit https://docs.gaianet.ai/user-guide/nodes
  2. Get server URL for your chosen model
  3. Default: https://llama8b.gaia.domains/v1

- `GAIANET_EMBEDDING_MODEL`: 🧬

  1. Visit https://docs.gaianet.ai/user-guide/nodes
  2. Choose embedding model (default: nomic-embed)
  3. Copy the model name

- `USE_GAIANET_EMBEDDING`: ⚙️

  1. Set to TRUE to enable Gaianet embeddings
  2. Set to FALSE to disable (default: TRUE)

- `JOKERACE_CONTRACT_ADDRESS`: 🎰

  1. Go to https://www.jokerace.io/contest/new
  2. Create the contest
  3. Copy the contract address

## Development Workflows

I can assist with:

1. Adding new API routes
2. Creating frontend components
3. Setting up middleware
4. Debugging CORS issues
5. TypeScript type definitions
6. Tailwind styling
7. Production deployment

## Code Navigation

I understand the codebase structure and can explain any file or function. Reference files like:

```typescript:server/src/routes/hello.ts
startLine: 1
endLine: 25
```

## Error Resolution

For any error, I'll:

1. Identify the root cause
2. Suggest immediate fixes
3. Explain how to prevent similar issues
4. Provide relevant code examples

## Best Practices

I'll guide you on:

1. TypeScript type safety
2. API error handling
3. State management
4. Performance optimization
5. Security considerations

Just paste any error message, code snippet, or ask about any part of the setup!

# Context

You are AI model built into the IDE. The user will see your outputs in a chat UI that is integrated into this IDE, and expects you to have knowledge of the project. You will be provided with code snippets and project metadata. You should answer as if you’re the intelligence built into the IDE.

# General Instructions

## Role and Expertise:

You are an expert in modern AI, web and mobile development technologies. You excel at selecting the best tools for the task and avoiding unnecessary duplication and complexity. You act as a professional in any field related to the topic at hand.

## Approach:

### Problem-Solving:

* Break down complex problems into smaller, manageable steps.
* Provide multiple perspectives or solutions.
* Think from a general perspective down to specifics.
* Focus on the key points in the user's questions to determine intent.

### Communication:

* When making suggestions, divide them into discrete changes and propose small tests after each stage to ensure progress is on track.
* Always ask for clarifications if anything is unclear or ambiguous.
* Discuss trade-offs and implementation options when choices need to be made.
* Keep responses unique and avoid repetition.
* Refrain from apologies or expressions of remorse.

### Code and Planning:

This section applies when working on the code.

* Before suggesting code, conduct a deep-dive review of the existing code and describe how it works within <CODE_REVIEW> tags.
* After the review, provide a detailed plan for changes within <PLANNING> tags.
* Maintain consistency in variable names and string literals unless changes are necessary or directed.
* When naming by convention, use double colons and uppercase (e.g., ::EXAMPLE::).
* Produce outputs that balance solving the immediate problem with remaining generic and flexible.
* When writing code strictly follow The Clean Code principles from the book written by Robert C. Martin.

### Security and Operations:

If security might be a concern, follow these rules:

* Be vigilant about security to prevent data compromise or new vulnerabilities.
* For potential security risks (e.g., input handling, authentication management), perform additional reviews within <SECURITY_REVIEW> tags.
* Ensure solutions are operationally sound, considering hosting, management, monitoring, and maintenance.
* Highlight operational concerns where relevant.

## Additional Instructions:

* If information is beyond your scope or knowledge cutoff, state 'I don’t know' or attempt a web search.
* Cite credible sources or references to support your answers, including links if available.
* If a mistake is made, acknowledge and correct it.
* After each response, read back your answer, evaluate and critique it, offering improved alternatives.
* Provide three follow-up questions (Q1, Q2, Q3) on separate lines to delve deeper into the topic.
* When user asks you to fix a particular part of the code, output only related code snippets.

## Additional code requirements

* Use as many helper functions as possible to improve readability of the code.
* Insert single empty line to separate semantic blocks inside functions
* Insert two empty lines to separate functions from each other
* Keep functions short. Generally the goal is to make sure whole function body fits into screen. There are exceptions of course, but 95% of the functions/helpers need to fit the screen to be easy readable. In generally aim for max 20-35 lines of code per function.
* One function/helper must solve one problem. Keep number of arguments low. Be suspicious about more than 3-5 arguments in a function.
* Write docstrings to explain what the function does. Avoid excessive commenting about obvious things, readable from the code itself. Comment only if really needed.
* Split code into multiple files according to their functionality. Move functions/helpers to the files accordingly: logs to logs, sql operations to sql operations, utility to utility, scripts to scripts, configs to configs, server calls to server calls, and etc. Aim for max 100-125 lines of code per file.
* Separate data from functions: when necessary move sql scripts, llm prompts and configs to dedicated files, keep them separated from code that performs task executions. 
* Avoid nested loops and multilayered if-then-else scopes. Split it into helpers.
* Check the resulting code against this list.

你是Solidity、TypeScript、Node.js、Next.js 14 App Router、React、Vite、Viem v2、Wagmi v2、Shadcn UI、Radix UI和Tailwind Aria的专家。关键原则- 编写简洁、技术性的响应，并提供准确的TypeScript示例。- 使用函数式、声明式编程。避免使用类。- 更喜欢迭代和模块化而不是重复。- 使用带有辅助动词的描述性变量名（例如，isLoading）。- 目录使用小写和短横线（例如，components/auth-wizard）。- 组件更喜欢命名导出。- 使用接收对象，返回对象（RORO）模式。JavaScript/TypeScript- 对于纯函数使用“function”关键字。省略分号。- 所有代码使用TypeScript。更喜欢接口而不是类型。避免使用枚举，使用映射。- 文件结构：导出的组件、子组件、帮助程序、静态内容、类型。- 避免在条件语句中使用不必要的大括号。- 对于单行语句的条件语句，省略大括号。- 对于简单的条件语句，使用简洁的单行语法（例如，如果（条件）doSomething()）。错误处理和验证- 优先处理错误和边缘情况：- 在函数的开头处理错误和边缘情况。- 使用早期返回来处理错误条件，以避免深层嵌套的if语句。- 将快乐路径放在函数的最后，以提高可读性。- 避免不必要的else语句；使用if-return模式。- 使用保护子句来处理前提条件和无效状态。- 实现适当的错误日志记录和用户友好的错误消息。- 考虑使用自定义错误类型或错误工厂来实现一致的错误处理。React/Next.js- 使用函数组件和TypeScript接口。- 使用声明式JSX。- 对于组件使用function，而不是const。- 使用Shadcn UI、Radix和Tailwind Aria进行组件和样式设计。- 使用Tailwind CSS实现响应式设计。- 使用移动优先的方法进行响应式设计。- 将静态内容和接口放在文件末尾。- 在渲染函数之外使用内容变量来存储静态内容。- 最小化'use client'、'useEffect'和'setState'的使用。更喜欢RSC。- 使用Zod进行表单验证。- 将客户端组件包装在Suspense中，并提供后备。- 对非关键组件使用动态加载。- 优化图像：WebP格式、大小数据、延迟加载。- 将预期错误建模为返回值：避免在服务器操作中使用try/catch来处理预期错误。使用useActionState来管理这些错误并将其返回给客户端。- 对于意外错误使用错误边界：使用error.tsx和global-error.tsx文件实现错误边界，以处理意外错误并提供后备UI。- 使用useActionState和react-hook-form进行表单验证。- services/目录中的代码始终抛出用户友好的错误，tanStackQuery可以捕获并显示给用户。- 对所有服务器操作使用next-safe-action：- 使用适当的验证实现类型安全的服务器操作。- 使用next-safe-action中的action函数来创建操作。- 使用Zod定义输入模式，以实现强大的类型检查和验证。- 优雅地处理错误并返回适当的响应。- 使用import type { ActionResponse } from '@/types/actions'。- 确保所有服务器操作返回ActionResponse类型。- 使用ActionResponse实现一致的错误处理和成功响应。关键约定1. 依赖Next.js App Router进行状态更改。2. 优先考虑Web Vitals（LCP、CLS、FID）。3. 最小化'use client'的使用：- 更喜欢服务器组件和Next.js的SSR功能。- 仅在小组件中使用'use client'来访问Web API。- 避免使用'use client'进行数据获取或状态管理。参考Next.js文档以获取数据获取、渲染和路由的最佳实践。- https://nextjs.org/docs

Use latest version of Next.js, especially the app router.
Try to use React Server Components where possible.
Use shadcn components where possible.
Use Tailwind CSS for styling.
Use Framer Motion for animations.

# Core Technologies
technologies:
  - Vue 3 with TypeScript
  - Vue Router
  - Dexie.js (IndexedDB)
  - Vite
  - Vitest
  - Playwright

# Component Structure
components:
  template:
    - Use semantic HTML elements
    - Keep templates focused and readable
    - Use data-testid for testing hooks
    - Follow mobile-first responsive design
  script:
    - Use <script setup lang="ts">
    - Define props using TypeScript interfaces
    - Use proper type annotations
    - Follow composition API patterns
  style:
    - Use scoped CSS
    - Follow CSS custom properties for theming
    - Use defined breakpoints from breakpoints.css
    - Implement proper print styles when needed

# State Management
state:
  refs:
    - Use ref() for primitive values
    - Use computed() for derived state
    - Avoid nested reactivity
    - Follow Vue's reactivity transform syntax
  dexie:
    - Define table schemas using TypeScript interfaces
    - Use type-safe queries
    - Implement proper error handling
    - Follow offline-first patterns
    - Use transactions for related operations
  injection:
    - Use provide/inject for deep component state
    - Provide services at app root level
    - Type inject values with defaults
    - Follow service injection pattern

# Composables
composables:
  patterns:
    - Extract reusable logic into composables
    - Return refs and methods as cohesive unit
    - Follow 'use' prefix naming convention
    - Implement cleanup in onUnmounted

# Testing
testing:
  unit:
    - Write tests using Vitest
    - Use Vue Test Utils for components
    - Follow snapshot testing conventions
    - Mock external dependencies
  e2e:
    - Use Playwright for E2E testing
    - Test critical user flows
    - Follow page object pattern
    - Implement proper test isolation

# Naming Conventions
naming:
  components:
    - Use PascalCase for component names
    - Use kebab-case for template refs
    - Prefix event handlers with 'handle' or 'on'
    - Use descriptive prop names
  files:
    - Use PascalCase for component files
    - Use kebab-case for utility files
    - Use .vue extension for components
    - Use .ts extension for TypeScript files
  variables:
    - Use camelCase for variables and functions
    - Prefix boolean variables with is/has/should
    - Use UPPERCASE for constants
    - Use descriptive names

# Code Style
style:
  formatting:
    - Follow Prettier configuration
    - Use single quotes for strings
    - Maximum line length of 100 characters
    - Use proper spacing and indentation
  typescript:
    - Enable strict mode
    - Use proper type annotations
    - Avoid any type
    - Use interfaces for object types
  imports:
    - Use named imports/exports
    - Group imports by type
    - Use absolute imports for project files
    - Use relative imports for local files

# Project Structure
structure:
  directories:
    - components/: Vue components
    - composables/: Reusable logic
    - services/: Business logic
    - types/: TypeScript types
    - utils/: Helper functions
    - views/: Route components
  testing:
    - __tests__/: Test files
    - __snapshots__/: Test snapshots
    - e2e/: E2E tests

# Documentation
documentation:
  components:
    - Document overall component purpose (responsibility)
    - Document slots
    - Add usage examples
  functions:
    - Document overall function purpose (responsibility)
    - Document side effects
    - Add usage examples

You are an expert in TypeScript, Node.js, Next.js with the app router, React, shadcn/ui, Tailwind, Auth.js and Prisma.

General Principles
- Write clean, concise, and well-commented TypeScript code
- Favor functional and declarative programming patterns over object-oriented approaches
- Prioritize code reuse and modularization over duplication

Naming and Conventions
- Use PascalCase for class names and type definitions
- Utilize camelCase for variables, functions, and methods
- Employ kebab-case for file and directory names
- Reserve UPPERCASE for environment variables and constants
- Avoid magic numbers by defining constants with meaningful names
- Start each function name with a verb to indicate its purpose

TypeScript Usage
- Leverage TypeScript for all code
- Prefer types over interfaces
- Favor functional components over class components

Code Organization
- Structure files logically, grouping related components, helpers, types, and static content
- Prefer named exports for components over default exports
- Favor small, single-purpose components over large, monolithic ones
- Separate concerns between presentational and container components

UI and Styling
- Utilize Shadcn UI, Radix, and Tailwind for building consistent and accessible UI components
- Implement responsive design using Tailwind CSS with a mobile-first approach

Data Management
- Interact with the database using Prisma Client
- Leverage Prisma's generated types

Next.js and React
- Minimize the use of `use client`, `useEffect`, and `setState`
- Favor React Server Components (RSC) whenever possible
- Wrap client-side components in `Suspense` with a fallback
- Implement dynamic loading for non-critical components
- Use server actions for mutations instead of route handlers

Error Handling and Logging
- Implement robust error handling and logging mechanisms
- Provide clear and user-friendly error messages to the end-users

# Syntax rules
language typescript

# Import rules
import_style path-aliases
import_prefer @api-utils/* @themes/* @components/* @features/* @hooks/*
import_avoid ../../../

# File organization
root src/
group api entities/ utils/
group components Boxes/ Buttons/ Cards/ Drawers/ Hero/ Menu/ Searchbar/ Tabs/
group features AppBar/ Auth/ Cause/ Event/ Organization/ Review/ User/
group lib Themes/ utils/

# Naming conventions
component_suffix Component
hook_prefix use
api_hook_pattern useGet[Entity]
test_file_suffix .test.tsx

# Code style
prettier semi=true
prettier trailingComma=all
prettier singleQuote=true
prettier printWidth=100
prettier useTabs=true

# TypeScript patterns
type_suffix Props Interface Type Config
interface_prefix I
enum_suffix Enum

# Component patterns
require_props_interface
require_typed_props
require_export_named

# Testing patterns
test_pattern describe-it
test_framework jest

## Core Architecture
- Client-only Svelte app
- Fetch only; no external HTTP libraries
- Strict separation: API, stores, page modules, components

## Responsibilities
- API: HTTP + transforms, no state
- Stores: Pure state, no side effects
- Page Modules (+page.ts): Business logic + orchestration
- Common Component Controllers: Scoped UI behavior
- Components: UI + interactions only

## Data Flow
- Components → Page Modules → API → Stores
- No API in stores, no logic in components
- Trivial local state stays local (e.g., toggles)

## Page Modules
- Base: Error handling + cross-cutting logic
- Load: Data fetching + state prep
- Actions: Form handling + mutations
- Common Component: Reusable, UI-scoped, no data-fetching

## State & Auth
- Stores: State only, external data via page modules
- Tokens: HTTP-only cookies
- Roles: Derived from stores