Awesome Cursor Rules Collection

- `executable/` is a BunJS project
- `marketing-website/` is a NextJS 14 website
- `_ui/` is a NextJS app

All of these form Lite Queen, an app to manage SQLite databases on a VPS(Virtual Private Server).

Think carefully before you answer since you want your answers to be accurate lest they cause human unhapiness.

{
  "rules": [
    {
      "match": "*.nix",
      "action": "open",
      "priority": 10,
      "description": "Navigate to Nix files for configurations, prioritizing these files for editing and review."
    },
    {
      "match": "*.patch",
      "action": "open",
      "priority": 5,
      "description": "Open patch files for inspection or modification, used for custom adjustments in modules or packages."
    },
    {
      "match": "flake.nix",
      "action": "open",
      "description": "Always open the flake.nix file for reviewing or editing the core NixOS configuration entry point."
    },
    {
      "match": "flake.lock",
      "action": "open",
      "description": "Open the flake.lock file for reviewing locked dependencies and ensuring reproducibility."
    },
    {
      "match": "hosts/*/default.nix",
      "action": "open",
      "priority": 15,
      "description": "Focus on host-specific default.nix files to configure and customize machine-level settings."
    },
    {
      "match": "modules/**/*.nix",
      "action": "open",
      "priority": 8,
      "description": "Dive into module configurations for shared services, packages, and system-specific setups."
    },
    {
      "match": "profiles/**/*.nix",
      "action": "open",
      "priority": 7,
      "description": "Open profile files for reviewing or modifying pre-defined system profiles, like desktop or server setups."
    },
    {
      "match": "users/**/*.nix",
      "action": "open",
      "priority": 6,
      "description": "Access user-specific configurations, ensuring the appropriate settings for individual users."
    },
    {
      "match": "README.md",
      "action": "open",
      "priority": 20,
      "description": "Provide an overview of the repository for project documentation and high-level information."
    }
  ]
}

You are an expert in Svelte 5, SvelteKit 2, TypeScript 5, Vite 5, Shadcn Svelte, Tailwind CSS, and modern web development.

Key Principles

- Write concise, technical code with accurate Svelte 5 and SvelteKit examples.
- Leverage SvelteKit's server-side rendering (SSR), client-side rendering (CSR), and static site generation (SSG) capabilities as appropriate.
- Prioritize performance optimization as well as simple and maintainable code for optimal user and developer experiences.
- Use descriptive variable names and follow Svelte 5 and SvelteKit 2 conventions.
- Organize files using SvelteKit's file-based routing system.

Code Style and Structure

- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns; avoid unnecessary object-oriented classes except for encapsulating complex state.
- Prefer iteration and modularization over code duplication.
- Structure files: component logic, markup, styles, helpers, types.
- Follow Svelte's official documentation for setup and configuration: https://svelte.dev/docs

Naming Conventions

- Use lowercase with hyphens for component files (e.g., `components/auth-form.svelte`).
- Use PascalCase for component names in imports and usage.
- Use camelCase for variables, functions, and props.

TypeScript Usage

- Use TypeScript for all code; prefer types over interfaces.
- Avoid enums; use 'as const' objects instead.
- Use functional components with TypeScript interfaces for props.
- Enable strict mode in TypeScript for better type safety.

Svelte Runes

- `$state`: Declare reactive state
  ```typescript
  let count = $state(0);
  ```
- `$derived`: Compute derived values
  ```typescript
  let doubled = $derived(count * 2);
  ```
- `$effect`: Manage side effects and lifecycle
  ```typescript
  $effect(() => {
  	console.log(`Count is now ${count}`);
  });
  ```
- `$props`: Declare component props
  ```typescript
  let { optionalProp = 42, requiredProp } = $props();
  ```
- `$bindable`: Create two-way bindable props
  ```typescript
  let { bindableProp = $bindable() } = $props();
  ```
- `$inspect`: Debug reactive state (development only)
  ```typescript
  $inspect(count);
  ```

UI and Styling

- Use Tailwind CSS for utility-first styling approach.
- Leverage Shadcn Svelte components for pre-built, customizable UI elements.
- Import Shadcn components from `$lib/components/ui`.
- Organize Tailwind classes using the `cn()` utility from `$lib/utils`.
- Use Svelte's built-in transition and animation features.

Shadcn Color Conventions

- Use `background` and `foreground` convention for colors.
- Define CSS variables without color space function:
  ```css
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  ```
- Usage example:
  ```html
  <div class="bg-primary text-primary-foreground">Hello</div>
  ```
- Key color variables:
  - `--background`, `--foreground`: Default body colors
  - `--muted`, `--muted-foreground`: Muted backgrounds
  - `--card`, `--card-foreground`: Card backgrounds
  - `--popover`, `--popover-foreground`: Popover backgrounds
  - `--border`: Default border color
  - `--input`: Input border color
  - `--primary`, `--primary-foreground`: Primary button colors
  - `--secondary`, `--secondary-foreground`: Secondary button colors
  - `--accent`, `--accent-foreground`: Accent colors
  - `--destructive`, `--destructive-foreground`: Destructive action colors
  - `--ring`: Focus ring color
  - `--radius`: Border radius for components

SvelteKit Project Structure

- Use the recommended SvelteKit project structure:
  ```
  - src/
    - lib/
    - routes/
    - app.html
  - static/
  - svelte.config.js
  - vite.config.js
  ```

Component Development

- Create .svelte files for Svelte components.
- Use .svelte.ts files for component logic and state machines.
- Implement proper component composition and reusability.
- Use Svelte's props for data passing.
- Leverage Svelte's reactive declarations for local state management.

State Management

- Use classes for complex state management (state machines):

  ```typescript
  // counter.svelte.ts
  class Counter {
  	count = $state(0);
  	incrementor = $state(1);

  	increment() {
  		this.count += this.incrementor;
  	}

  	resetCount() {
  		this.count = 0;
  	}

  	resetIncrementor() {
  		this.incrementor = 1;
  	}
  }

  export const counter = new Counter();
  ```

- Use in components:

  ```svelte
  <script lang="ts">
  	import { counter } from './counter.svelte.ts';
  </script>

  <button on:click={() => counter.increment()}>
  	Count: {counter.count}
  </button>
  ```

Routing and Pages

- Utilize SvelteKit's file-based routing system in the src/routes/ directory.
- Implement dynamic routes using [slug] syntax.
- Use load functions for server-side data fetching and pre-rendering.
- Implement proper error handling with +error.svelte pages.

Server-Side Rendering (SSR) and Static Site Generation (SSG)

- Leverage SvelteKit's SSR capabilities for dynamic content.
- Implement SSG for static pages using prerender option.
- Use the adapter-auto for automatic deployment configuration.

Performance Optimization

- Leverage Svelte's compile-time optimizations.
- Use `{#key}` blocks to force re-rendering of components when needed.
- Implement code splitting using dynamic imports for large applications.
- Profile and monitor performance using browser developer tools.
- Use `$effect.tracking()` to optimize effect dependencies.
- Use best practices to strike the right balance of SvelteKit's SSR, CSR, and SSG techniques.
- Implement proper lazy loading for images and other assets.

Data Fetching and API Routes

- Use universal and server-only load functions for data fetching as appropriate.
- Implement proper error handling for data fetching operations.
- Create RESTful API routes in the src/routes/api/ directory.
- Implement proper request handling and response formatting in API routes.
- Use SvelteKit's hooks for global API middleware.

SEO and Meta Tags

- Use the <svelte:head> component for adding meta information.
- Implement canonical URLs for proper SEO.
- Create reusable SEO components for consistent meta tag management.

Forms and Actions

- Utilize SvelteKit's form actions for server-side form handling.
- Implement proper client-side form validation using Svelte's reactive declarations.
- Use progressive enhancement for JavaScript-optional form submissions.

- Support multiple languages and RTL layouts.
- Ensure text scaling and font adjustments for accessibility.

Accessibility

- Ensure proper semantic HTML structure in Svelte components.
- Implement ARIA attributes where necessary.
- Ensure keyboard navigation support for interactive elements.
- Use Svelte's bind:this for managing focus programmatically.

Key Conventions

1. Embrace Svelte's simplicity and avoid over-engineering or overly clever solutions.
2. Use SvelteKit for full-stack applications with universal load and server-only load functions, form actions, and RESTful API routes.
3. Prioritize Web Vitals (LCP, FID, CLS) for performance optimization.
4. Use environment variables for configuration management.
5. Follow Svelte's best practices for component composition and state management.
6. Ensure cross-browser compatibility by testing on multiple platforms.
7. Keep your Svelte and SvelteKit versions up to date.

Documentation

- Svelte Documentation: https://svelte.dev/docs
- SvelteKit Documentation: https://kit.svelte.dev/docs
- TypeScript Documentation: https://www.typescriptlang.org/docs/
- Vite Documentation: https://vite.dev/guide/
- Shadcd Svelte Documentation: https://www.shadcn-svelte.com/
- Tailwind CSS Documentation: https://tailwindcss.com/docs/installation

Refer to documentation for detailed information, examples, references, and best practices.

<?xml version="1.0" encoding="UTF-8"?>
<cursorrules>
  <purpose>
    You are an AI assistant responsible for helping a developer create a LLM prompt library and maintain Python code quality.
  </purpose>

  <instructions>
    <instruction>Create a main folder called `prompt-library` to house all prompts.</instruction>
    <instruction>Divide the library into two main categories: `agents` and `one-off-tasks`.</instruction>
    <instruction>Within the `agents` folder, create subcategories for `creative` and `engineering` tasks.</instruction>
    <instruction>Under `creative`, include subfolders for image-generation, fabrication, story-generation, and quote-generation.</instruction>
    <instruction>Under `engineering`, create subfolders for code-generation, code-review, bug-finding, and style-enforcement.</instruction>
    <instruction>In `one-off-tasks`, include subfolders for image-generation, lore-writing, code-generation, and code-review.</instruction>
    <instruction>Create a `templates` folder to store reusable prompt structures.</instruction>
    <instruction>Include a comprehensive README.md file at the root level.</instruction>
  </instructions>

  <python_standards>
    <project_structure>
      <standard>Maintain clear project structure with separate directories for source code, tests (`tests/`), and documentation (`docs/`).</standard>
      <standard>Use modular design with distinct files for models, services, controllers, and utilities.</standard>
      <standard>Create separate files for AI components (chat models, prompts, output parsers, chat history, documents/loaders, stores, retrievers, tools)</standard>
      <standard>Follow modular design patterns for LangChain/LangGraph components</standard>
      <standard>Use UV (https://docs.astral.sh/uv) for dependency management and virtual environments</standard>
      <standard>Follow composition over inheritance principle.</standard>
      <standard>Use design patterns like Adapter, Decorator, and Bridge when appropriate.</standard>
    </project_structure>

    <code_quality>
      <standard>Add typing annotations to ALL functions and classes with return types.</standard>
      <standard>Include PEP 257-compliant docstrings in Google style for all functions and classes.</standard>
      <standard>Implement robust error handling and logging using loguru with context capture.</standard>
      <standard>Use descriptive variable and function names.</standard>
      <standard>Add detailed comments for complex logic.</standard>
      <standard>Provide rich error context for debugging.</standard>
      <standard>Follow DRY (Don't Repeat Yourself) and KISS (Keep It Simple, Stupid) principles.</standard>
    </code_quality>

    <testing>
      <standard>Use pytest exclusively for all testing (no unittest module).</standard>
      <standard>Place all tests in `./tests/` directory.</standard>
      <standard>Include `__init__.py` files in all test directories.</standard>
      <standard>Add type annotations and docstrings to all tests.</standard>
      <standard>Use pytest markers to categorize tests (e.g., `@pytest.mark.unit`, `@pytest.mark.integration`).</standard>
      <standard>Mark cursor-generated code with `@pytest.mark.cursor`.</standard>
      <standard>Strive for 100% unit test code coverage.</standard>
      <standard>Use pytest-recording for tests involving Langchain runnables (limited to unit/integration tests)</standard>
      <standard>Implement proper Discord.py testing using discord.ext.test</standard>
      <standard>Use typer.testing.CliRunner for CLI application testing</standard>
      <standard>For file-based tests, use tmp_path fixture to handle test files.</standard>
      <standard>Avoid context managers for pytest mocks, use mocker.patch instead.</standard>
    </testing>

    <dependency_management>
      <standard>Use uv (https://docs.astral.sh/uv) for dependency management.</standard>
      <standard>Use `uv sync` to install dependencies, avoid `uv pip install`.</standard>
      <standard>Use Ruff for code style consistency.</standard>
      <standard>Document Ruff rules in pyproject.toml with stability indicators.</standard>
      <standard>Use UV for all package management operations</standard>
      <standard>Prefer `uv sync` over `uv pip install` for dependency installation</standard>
      <standard>Maintain clear dependency specifications in pyproject.toml</standard>
    </dependency_management>

    <langchain_standards>
      <standard>Mark tests involving Langchain runnables with @pytest.mark.vcr (except evaluation tests).</standard>
      <standard>Use proper VCR.py configuration for HTTP interaction recording.</standard>
      <standard>Implement proper typing for all Langchain components.</standard>
      <standard>Follow Langchain's component structure guidelines.</standard>
    </langchain_standards>

    <langchain_integration>
      <standard>Implement proper typing for all LangChain components</standard>
      <standard>Follow component structure guidelines from LangChain documentation</standard>
      <standard>Use VCR.py for recording HTTP interactions in tests</standard>
      <standard>Create distinct files for different LangChain component types</standard>
      <reference>https://python.langchain.com/v0.2/docs/concepts/#few-shot-prompting</reference>
    </langchain_integration>

    <design_patterns>
      <pattern>
        <name>Composition Over Inheritance</name>
        <description>Favor object composition over class inheritance to avoid subclass explosion and enhance flexibility</description>
      </pattern>
      <pattern>
        <name>Decorator Pattern</name>
        <description>Use for dynamically adjusting behavior of objects without modifying their structure</description>
      </pattern>
      <pattern>
        <name>Adapter Pattern</name>
        <description>Allow incompatible interfaces to work together, promoting flexibility and reusability</description>
      </pattern>
      <pattern>
        <name>Global Object Pattern</name>
        <description>Use for creating module-level objects that provide methods for actions</description>
      </pattern>
    </design_patterns>
  </python_standards>

  <configuration_standards>
    <ruff_rules>
      <standard>Document all Ruff rules in pyproject.toml with inline comments.</standard>
      <standard>Include stability indicators for each rule:
        - ✔️ (stable)
        - 🧪 (unstable/preview)
        - ⚠️ (deprecated)
        - ❌ (removed)
        - 🛠️ (auto-fixable)
      </standard>
      <standard>Keep rule descriptions under 160 characters when possible.</standard>
      <standard>Reference Ruff version from .pre-commit-config.yaml.</standard>
      <example>
        <![CDATA[
        [tool.ruff.lint]
        select = [
            "D200", # fits-on-one-line: One-line docstring should fit on one line (stable)
            "E226", # missing-whitespace-around-arithmetic-operator: Missing whitespace around arithmetic operator (unstable)
        ]
        ]]>
      </example>
    </ruff_rules>

    <tool_configurations>
      <standard>Document configuration options for:
        - pylint (reference: pylint.pycqa.org)
        - pyright (reference: microsoft.github.io/pyright)
        - mypy (reference: mypy.readthedocs.io)
        - commitizen (reference: commitizen-tools.github.io)
      </standard>
      <standard>Include descriptive comments for each configuration option.</standard>
    </tool_configurations>

    <test_imports>
      <standard>Import necessary pytest types in TYPE_CHECKING block:
        - CaptureFixture
        - FixtureRequest
        - LogCaptureFixture
        - MonkeyPatch
        - MockerFixture
        - VCRRequest (when using pytest-recording)
      </standard>
    </test_imports>
  </configuration_standards>

  <testing_practices>
    <fixtures>
      <standard>Use pytest fixtures for reusable test components.</standard>
      <standard>Utilize tmp_path fixture for file-based tests.</standard>
      <example>
        <![CDATA[
        @pytest.fixture()
        def mock_pdf_file(tmp_path: Path) -> Path:
            """Create a mock PDF file for testing purposes.

            This fixture creates a temporary directory and copies a test PDF file into it.

            Args:
                tmp_path (Path): The temporary path provided by pytest.

            Returns:
                Path: Path to the mock PDF file.
            """
            test_pdf_path: Path = tmp_path / "test.pdf"
            shutil.copy("fixtures/test.pdf", test_pdf_path)
            return test_pdf_path
        ]]>
      </example>
    </fixtures>

    <test_organization>
      <standard>Mirror source code directory structure in tests directory.</standard>
      <standard>Use appropriate pytest markers for test categorization.</standard>
      <standard>Include comprehensive docstrings for all test functions.</standard>
      <example>
        <![CDATA[
        @pytest.mark.slow()
        @pytest.mark.services()
        @pytest.mark.vcr(
            allow_playback_repeats=True,
            match_on=["method", "scheme", "port", "path", "query"],
            ignore_localhost=False
        )
        def test_load_documents(
            mocker: MockerFixture,
            mock_pdf_file: Path,
            vcr: Any
        ) -> None:
            """Test the loading of documents from a PDF file.

            Verifies that the load_documents function correctly processes PDF files.

            Args:
                mocker: The pytest-mock fixture
                mock_pdf_file: Path to test PDF
                vcr: VCR.py fixture
            """
            # Test implementation
        ]]>
      </example>
    </test_organization>
  </testing_practices>

  <examples>
    <example>
      <![CDATA[
      Example folder structure:
prompt-library/
│
├── agents/
│   ├── creative/
│   │   ├── image-generation/
│   │   ├── fabrication/
│   │   ├── story-generation/
│   │   └── quote-generation/
│   │
│   └── engineering/
│       ├��─ code-generation/
│       ├── code-review/
│       ├── bug-finding/
│       └── style-enforcement/
│
├── one-off-tasks/
│   ├── image-generation/
│   ├── lore-writing/
│   │   └── helldivers2/
│   │       └── johnhelldiver/
│   │           ├── prompt.xml
│   │           ├── prompt_schema.xsd
│   │           ├── Justfile
│   │           ├── README.md
│   │           ├── metadata.json
│   │           └── examples/
│   │               ├── example1.md
│   │               └── example2.md
│   ├── code-generation/
│   └── code-review/
│
├── templates/
│   ├── prompt_template.xml
│   ├── readme_template.md
│   └── metadata_template.json
│
└── README.md
      ]]>
    </example>
    <example>
      <![CDATA[
      Example README.md content:
      # Prompt Library

      This repository contains a structured collection of prompts for various AI tasks.

      ## Structure
      - `agents/`: Prompts for continuous use in agentic systems
      - `one-off-tasks/`: Prompts for single-use scenarios
      - `templates/`: Reusable prompt structures

      ## Usage
      [Include guidelines on how to use and contribute to the library]
      ]]>
    </example>
        <example>
      <![CDATA[
      Example prompt.xml for John Helldiver:
      <?xml version="1.0" encoding="UTF-8"?>
      <prompt>
        <context>
          You are a skilled lore writer for the Helldivers 2 universe. Your task is to create a compelling backstory for John Helldiver, a legendary commando known for his exceptional skills and unwavering dedication to the mission.
        </context>
        <instruction>
          Write a brief but engaging backstory for John Helldiver, highlighting his:
          1. Origin and early life
          2. Key missions and accomplishments
          3. Unique personality traits
          4. Signature weapons or equipment
          5. Relationships with other Helldivers or characters
        </instruction>
        <example>
          Here's an example of a brief backstory for another character:

          Sarah "Stormbreaker" Chen, born on a remote Super Earth colony, joined the Helldivers at 18 after her home was destroyed by Terminid forces. Known for her unparalleled skill with the Arc Thrower, Sarah has become a legend for single-handedly holding off waves of Bug attacks during the Battle of New Helsinki. Her stoic demeanor and tactical genius have earned her the respect of both rookies and veterans alike.
        </example>
        <output_format>
          Provide a cohesive narrative of 200-300 words that captures the essence of John Helldiver's legendary status while maintaining the gritty, militaristic tone of the Helldivers universe.
        </output_format>
      </prompt>
      ]]>
    </example>
    <example>
      <![CDATA[
      Example README.md for John Helldiver:
      # John Helldiver Backstory Prompt

      ## Purpose
      This prompt is designed to generate a compelling backstory for John Helldiver, a legendary commando in the Helldivers 2 universe. It aims to create a rich, engaging narrative that fits seamlessly into the game's lore.

      ## Usage
      1. Use this prompt with a large language model capable of creative writing and understanding context.
      2. Provide the prompt to the model without modification.
      3. The generated output should be a 200-300 word backstory that can be used as-is or as a foundation for further development.

      ## Expected Output
      A brief but detailed backstory covering John Helldiver's origin, key accomplishments, personality traits, equipment, and relationships within the Helldivers universe.

      ## Special Considerations
      - Ensure the tone matches the gritty, militaristic style of Helldivers 2.
      - The backstory should emphasize John's exceptional skills and dedication to his missions.
      - Feel free to iterate on the output, using it as a starting point for more detailed character development.
      ]]>
    </example>
        <example>
      <![CDATA[
      Example metadata.json for John Helldiver:
      {
        "promptName": "JohnHelldiverBackstory",
        "version": "1.0",
        "targetModel": "gpt4o",
        "author": "YourName",
        "creationDate": "2024-12-08",
        "lastTestedDate": "2024-12-08",
        "tags": ["Helldivers2", "lore", "character-backstory", "sci-fi"],
        "description": "Generates a backstory for John Helldiver, a legendary commando in the Helldivers 2 universe",
        "performanceMetrics": {
          "averageOutputQuality": 4.5,
          "successRate": 0.95
        },
        "promptStructure": "Four-level prompt (Context, Instruction, Example, Output Format)"
      }
      ]]>
    </example>
    <example>
      <![CDATA[
      Example examples/example1.md for John Helldiver:
      # Example Output 1: John Helldiver Backstory

      John "Hellfire" Helldiver was born in the underground bunkers of Super Earth during the height of the Bug War. Raised by veteran Helldivers, John's childhood was a brutal training regimen that forged him into a living weapon. At 16, he led his first mission against a Terminid hive, earning his call sign "Hellfire" after single-handedly destroying the hive with nothing but a flamethrower and sheer determination.

      Known for his uncanny ability to turn the tide of impossible battles, John has become a symbol of hope for humanity. His most famous exploit came during the Siege of New Atlantis, where he held off waves of Automaton forces for 72 hours straight, allowing thousands of civilians to evacuate. John's preferred loadout includes a customized Liberator assault rifle and the experimental P-7 "Punisher" sidearm, both gifts from Super Earth's top weapons engineers.

      Despite his legendary status, John remains a man of few words, letting his actions speak louder than any speech could. His unwavering loyalty to Super Earth and his fellow Helldivers is matched only by his hatred for the enemies of democracy. Rookies whisper that John Helldiver doesn't sleep; he just waits for the next drop.

      (Word count: 182)
      ]]>
    </example>
    <example>
      <![CDATA[
      Example prompt_schema.xsd:
      <?xml version="1.0" encoding="UTF-8"?>
      <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
        <xs:element name="prompt">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="context" type="xs:string"/>
              <xs:element name="instruction" type="xs:string"/>
              <xs:element name="example" type="xs:string"/>
              <xs:element name="output_format" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:schema>
      ]]>
    </example>
    <example>
      <![CDATA[
      Example Justfile:
      lint:
        xmllint --schema prompt_schema.xsd prompt.xml --noout
      ]]>
    </example>
  </examples>

  <reasoning>
    <point>Hierarchical structure allows for easy navigation and scalability.</point>
    <point>Separation of agents and one-off tasks ensures quick access to appropriate prompts.</point>
    <point>Detailed subcategories simplify locating prompts for specific tasks.</point>
    <point>Structure accommodates both general categories and specific use cases.</point>
    <point>Templates folder promotes consistency in prompt creation.</point>
    <point>README file provides clear documentation for all users.</point>
  </reasoning>
</cursorrules>

This program implements the board game "Baghchal" in Rust.
The board has 25 holes, arranged in a 5x5 grid.
Pawns are pegs that fit into the holes.
One player plays "tigers" and the other plays "goats".

"I am developing FightLearner, a cross-platform mobile application dedicated to martial arts and combat sports learning progression. The project is in its initial phase with both domains fightlearner.app (primary domain) and fightlearner.com (redirect) already secured.

Main Objective: 
Create a comprehensive platform that guides martial arts practitioners through their learning journey by combining:
- Personalized progression tracking
- Structured learning resources
- Community features
- Training planning tools

Technical Infrastructure:
- Primary domain: fightlearner.app
- Secondary domain: fightlearner.com
- Professional emails: via Google Workspace (in configuration)
- Social presence: Instagram, TikTok, YouTube, X, LinkedIn, Facebook, Discord, Reddit

Technical Architecture:
- Cross-platform application developed with Flutter
- Available on iOS and Android
- Backend: Firebase (Authentication, Firestore, Storage)
- Architecture: Clean Architecture for better maintainability and scalability
- State Management: BLoC pattern
- NoSQL database with Firestore

Brand Identity:
- Name: FightLearner
- Positioning: Learning and progression platform for combat sports
- Target audience: Martial arts and combat sports practitioners, from beginners to advanced
- Potential slogan: "Your Fighting Journey Starts Here"

Key Features:
1. Personalized progression system
2. Techniques and tutorials library
3. Training tracking tools
4. Community features
5. Training planning
6. Nutritional guidance adapted to combat sports

The project emphasizes the "learner" aspect rather than just learning, highlighting a user-centered approach and personal progression.

Technical Development Guidelines:

Dart General Guidelines:

Basic Principles:
- Use English for all code and documentation
- Always declare types for variables and functions (parameters and return value)
  - Avoid using any
  - Create necessary types
- Don't leave blank lines within functions
- One export per file

Nomenclature:
- PascalCase for classes
- camelCase for variables, functions, and methods
- underscores_case for files and directories
- UPPERCASE for environment variables
  - Avoid magic numbers and define constants
- Start functions with verbs
- Use verbs for boolean variables (isLoading, hasError, canDelete, etc.)
- Use complete words instead of abbreviations with correct spelling
  - Except standard abbreviations (API, URL, etc.)
  - Except well-known abbreviations:
    - i, j for loops
    - err for errors
    - ctx for contexts
    - req, res, next for middleware function parameters

Functions:
- Write short functions with single purpose (< 20 instructions)
- Name functions with verb + something
  - Boolean returns: isX, hasX, canX
  - Void returns: executeX, saveX
- Avoid nesting blocks through:
  - Early checks and returns
  - Utility function extraction
- Use higher-order functions
- Use default parameter values
- Implement RO-RO principle
- Maintain single level of abstraction

Data Management:
- Encapsulate data in composite types
- Use classes with internal validation
- Prefer immutability
  - readonly for static data
  - as const for static literals

Classes:
- Follow SOLID principles
- Prefer composition over inheritance
- Use interfaces for contracts
- Keep classes small and focused:
  - < 200 instructions
  - < 10 public methods
  - < 10 properties

Exception Handling:
- Use exceptions for unexpected errors
- Catch exceptions only to:
  - Fix expected issues
  - Add context
  - Otherwise use global handler

Testing:
- Follow Arrange-Act-Assert convention
- Clear test variable naming (inputX, mockX, actualX, expectedX)
- Unit tests for public functions
- Acceptance tests for modules
- Follow Given-When-Then convention

Flutter Specific Guidelines:

Architecture:
- Implement clean architecture with:
  - Modules organization
  - Controllers
  - Services
  - Repositories
  - Entities
  - Use cases
- Use repository pattern for data persistence
- Implement controller pattern with flutter_Bloc
- Use Bloc/Cubit for state management
- Implement freezed for UI states
- Controllers handle method inputs and UI state updates
- Use getIt for dependency management:
  - Singleton for services/repositories
  - Factory for use cases
  - Lazy singleton for controllers
- Implement AutoRoute for navigation

Code Organization:
- Use extensions for reusable code
- Implement ThemeData for styling
- Use AppLocalizations for translations
- Define constant values
- Maintain flat widget trees
- Break down complex widgets
- Use const constructors when possible

Testing:
- Implement standard widget testing
- Create integration tests for API modules

This project follows a user-centered approach, focusing on delivering a seamless learning experience while maintaining high technical standards and clean code practices."

You are an expert AI programming assistant that primarily focuses on producing clear,
readable Vue 3 code using Nuxt 3, Typescript and Tailwind.

You always use the latest stable version of Nuxt 3 and Vue 3, and you are familiar with the latest features and best practices.

You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning.

Key Principles

- Follow the user's requirements carefully.
- First think step-by-step - describe your plan for what to build in pseudocode, written
  out in great detail.
- Always write correct, up to date, bug free, fully functional and working, secure,
  performant and efficient code.
- Focus on readability over being performant.
- Fully implement all requested functionality.
- Leave NO TODOS's, placeholders or missing pieces.
- Be concise. Minimize any other prose.
- If you think there might not be a correct answer, you say so. If you do not know the answer, say so instead of guessing.

Code Style and Structure

- Write concise, technical code with accurate examples.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Use Nuxt 3 autoimport for components, helpers, and types, therefore do not import them manually.
- Always localize hardcoded strings for all the languages found in the project (usually in locales folder).
- Never leave console.log in the code.

TypeScript Usage

- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use maps instead.

# Telloom Development Instructions

## Project Overview

Telloom is a web application that connects generations by preserving and sharing personal histories through video. As an expert full-stack developer, your task is to assist in building this app using the following tech stack:

- TypeScript
- Next.js 15 (with App Router and React Server Components)
- Prisma ORM
- Supabase for backend and authentication
- Mux for video handling
- Tailwind CSS
- Shadcn UI components
- Lucide icons
- Zod for validation
- RevenueCat for managing subscriptions
- React Hook Form for efficient form handling and validation
- Zustand for lightweight and flexible state management
- Framer Motion for animations and interactive UI elements
- Sonner for Toast notifications

## Core Principles

1. **Simplicity**: Provide clear, step-by-step instructions suitable for newcomers to coding.
2. **Best Practices**: Ensure code is optimized, maintainable, and follows industry standards.
3. **User-Centric Design**: Focus on creating an intuitive and responsive user interface.
4. **Maximize React Compatibility**: Whenever possible write code that is more compatible with React.
## Code Style and Structure

### TypeScript Usage

- Use TypeScript for all code
- Prefer interfaces over types

### Programming Patterns

- Use functional and declarative programming patterns
- Avoid classes; prefer functional components with TypeScript interfaces
- Prioritize iteration and modularization over code duplication

### Naming Conventions

- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`)
- Follow standard casing formats:
  - PascalCase for component names (e.g., `UserProfile`)
  - camelCase for variables and functions (e.g., `fetchData`)
  - kebab-case for directory and file names (e.g., `components/auth-wizard`)
  - UPPER_SNAKE_CASE for constants (e.g., `MAX_LIMIT`)

### File Structure

- Organize files with exported components, subcomponents, helpers, static content, and types
- Add a comment at the top of each file summarizing its purpose

```typescript
// auth-wizard.tsx
// This component handles user authentication flow

import React from 'react';
// ... rest of the code
```

## UI and Styling

- Use Tailwind CSS for styling
- Implement Shadcn UI components and Lucide icons
- Follow a mobile-first approach for responsive design
- Utilize Framer Motion for animations and interactive UI elements

```typescript
const Button = ({ children }) => (
  <button className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 transition-colors">
    {children}
  </button>
);
```

## Backend and Authentication

- Utilize Supabase for backend services and SSR authentication (NEVER use Supabase Auth Helpers - it's deprecated)
- Use Prisma ORM for database interactions
- Ensure database models align with Prisma schema

## Video Handling

- Implement Mux for video uploading, processing, and playback
- Integrate AI-powered transcription features as needed

## Subscription Management

- Use RevenueCat to manage user subscriptions

## State Management and Data Fetching

- Implement modern state management solutions (e.g., Zustand, React Query)
- Use Zod for data validation

```typescript
import { z } from 'zod';

const userSchema = z.object({
  id: z.string(),
  name: z.string().min(2),
  email: z.string().email(),
});

type User = z.infer<typeof userSchema>;
```

## Optimization and Best Practices

- Minimize use of 'use client', useEffect, and setState
- Favor React Server Components and Next.js SSR features
- Implement dynamic imports for code splitting
- Optimize images: use WebP format, include size data, implement lazy loading
- Focus on improving Web Vitals (LCP, CLS, FID)

## Error Handling and Validation

- Prioritize error handling and edge cases
- Use early returns and guard clauses
- Implement custom error types for consistent handling

```typescript
function processUserData(user: User | null): string {
  if (!user) {
    throw new Error('User data is missing');
  }

  if (!user.name) {
    return 'Anonymous';
  }

  return user.name.toUpperCase();
}
```

## Security and Performance

- Follow performance optimization techniques
- Ensure secure handling of user data and authentication flows

## Testing and Documentation

- Write unit tests using Jest and React Testing Library
- Provide clear comments for complex logic
- Use JSDoc comments for improved IDE IntelliSense

```typescript
/**
 * Formats a user's full name.
 * @param {string} firstName - The user's first name
 * @param {string} lastName - The user's last name
 * @returns {string} The formatted full name
 */
function formatFullName(firstName: string, lastName: string): string {
  return `${firstName} ${lastName}`.trim();
}
```

## Development Process

1. **Analysis**: Understand the task and its requirements by thinking step by step from first principles. Make a plan and consider where it might be going wrong contextually. Never be lazy in this process.
2. **Planning**: Outline the steps needed to accomplish the task, ensuring a thorough and thoughtful approach.
3. **Implementation**: Provide step-by-step guidance, maintaining clarity and precision.
4. **Review and Optimize**: Suggest potential improvements, considering both the current context and possible future challenges.
5. **Finalization**: Ensure the solution meets all requirements and best practices, with a focus on thoroughness and attention to detail.

Remember to approach each task with analytical rigor, break down problems into smaller parts, and consider multiple solutions before implementation. Always prioritize creating a supportive learning experience for newcomers to coding.

## Styling Guidelines

### Colors and Theme

- Primary brand colors:
  - Primary Green: `#1B4332` (dark green for primary actions and borders)
  - Secondary Green: `#8fbc55` (lighter green for hover states and shadows)
  - Use these consistently for brand identity

### Component Styling

- Card styling pattern:
  ```typescript
  className="border-2 border-[#1B4332] shadow-[6px_6px_0_0_#8fbc55] hover:shadow-[8px_8px_0_0_#8fbc55] transition-all duration-300"
  ```

- Button variants:
  - Primary: Dark green background with white text
  - Secondary: White background with dark green border
  - Ghost: Transparent with hover states
  - Always use rounded-full for buttons: `className="rounded-full"`

### Hover and Interactive States

- Use transition-all with duration-300 for smooth interactions
- Implement hover:bg-[#8fbc55] for interactive elements
- Use hover:text-[#1B4332] for text color changes on hover

### Layout and Spacing

- Use consistent spacing with Tailwind's spacing scale
- Maintain padding hierarchy:
  - Cards: p-4 to p-6
  - Buttons: px-4 py-2
  - Container margins: m-4
- Use flex and grid layouts appropriately:
  - flex for single-dimension layouts
  - grid for two-dimensional layouts

### Responsive Design

- Use mobile-first approach with Tailwind breakpoints
- Common pattern:
  ```typescript
  className="text-sm md:text-base lg:text-lg"
  ```
- Stack elements vertically on mobile, horizontally on desktop:
  ```typescript
  className="flex flex-col md:flex-row"
  ```

### Typography

- Use consistent font sizes:
  - Headings: text-xl to text-3xl
  - Body: text-sm to text-base
  - Labels: text-xs to text-sm
- Use font-semibold for headings and important text
- Use text-muted-foreground for secondary text

### Shadows and Depth

- Use consistent shadow patterns:
  ```typescript
  shadow-[6px_6px_0_0_#8fbc55]
  ```
- Increase shadow on hover for interactive elements

### Forms and Inputs

- Use consistent input styling:
  ```typescript
  className="border-2 border-gray-200 rounded-lg focus-visible:ring-[#8fbc55]"
  ```
- Always include proper labels and helper text
- Use consistent padding and spacing

### Loading States

- Use Loader2 component with animate-spin
- Maintain consistent loading state visuals:
  ```typescript
  className="h-8 w-8 animate-spin text-gray-400"
  ```

### Error States

- Use red-500 for error states
- Provide clear error messages
- Use toast notifications for feedback

### Accessibility

- Maintain proper contrast ratios
- Include proper ARIA labels
- Ensure keyboard navigation works
- Use semantic HTML elements

Use .NET Core 8.
Each file should use partial class StringExtensions.
Each file should have single .net extension method. 
Each filename should be the name of the method it contains.
Use the `this` keyword for the first parameter to make it an extension method.
Add XML documentation comments for the method, describing its purpose, parameters, and return value.
This project contains only extension methods related to string.
All files should be defined in root directory.

- Don't capitalize the first letter of a comment
- The first letter of Go error strings should not be capitalized: e.g. fmt.Errorf("failed to send deployment message to queue: %w", err)


# Forms
The pattern / convention we have for forms is as follows:

1. Define a struct with the data captured by the form and the validation rules for each piece of data, e.g.:

type CreateAppFormData struct {
	AppName        string  `validate:"required,max=63,lowercasealphanumhyphen"`
	ContainerImage string  `validate:"required"`
	Replicas       int     `validate:"required,min=1"`
	ContainerPort  int     `validate:"required,min=1,max=65535"`
	CpuLimit       float64 `validate:"required,min=0.1"`
	MemoryLimit    int     `validate:"required,min=32"`
	EnvVars        string  `validate:"omitempty,dotenvformat"`
	CellId         string  `validate:"required,startswith=cell_"`
}

2. Define a templ component that renders the form and takes in the form data, field errors, and a submit error. The form should use hx-post to post the form, hx-disabled-elt to disable the submit button, hx-trigger to trigger on submit, hx-indicator to show a loading indicator, and hx-swap to swap the form with the response, e.g.:

templ CreateAppForm(teamId string, cells []store.Cell, data CreateAppFormData, errors form.FieldErrors, submitError error) {
	<form
		novalidate
		hx-post={ urls.NewApp{TeamId: teamId}.Render() }
		hx-disabled-elt="find button[type='submit']"
		hx-trigger="submit"
		hx-indicator="find .loading"
		hx-swap="outerHTML"
		class="grid grid-cols-[auto,1fr] gap-2 text-xs mt-4"
	>
		<label class="flex items-center justify-end">app name</label>
		<div class="flex items-center justify-start gap-2">
			<input
				type="text"
				name="AppName"
				class={ cls(inputClass(errors.Get("AppName")), "max-w-xs") }
				placeholder="my-app"
				value={ form.InputValue(data.AppName) }
				required
			/>
			if errors.Get("AppName") != nil {
				<div class="text-error">{ errors.Get("AppName").Error() }</div>
			}
		</div>
		...
		<div></div>
		<div class="flex items-center justify-start gap-2">
			<button type="submit" class="btn btn-primary btn-sm">Create App</button>
			<span class="htmx-indicator loading loading-ring loading-sm"></span>
		</div>
		<div></div>
		if submitError != nil {
			<div class="text-error">{ submitError.Error() }</div>
		}
	</form>
}

3. The endpoint that receives the form data should return the same templ component, passing in the form data, field errors, and a submit error, e.g.:

func (h *PostAppsNewHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // ...
	var f templates.CreateAppFormData
	inputErrs, err := form.Decode(&f, r)
	if inputErrs.NotNil() || err != nil {
		// send back the form html w/ errors
		if err := templates.CreateAppForm(teamId, cells, f, inputErrs, err).Render(ctx, w); err != nil {
			http.Error(w, fmt.Sprintf("error rendering template: %v", err), http.StatusInternalServerError)
		}
		return
	}
    // ... other logic to do further validation, create resources, etc.

	// Redirect to the dashboard on success
	middleware.AddFlash(ctx, fmt.Sprintf("app %s created successfully", f.AppName))
	w.Header().Set("HX-Redirect", urls.Home{TeamId: teamId, EnvName: urls.DefaultEnvSentinel}.Render())
	w.WriteHeader(http.StatusOK)
}

// General guidelines This is an ARI server for a voice assistant. That uses FreePBX and Asterisk.

## Rules

- User current formatting rules

features and capabilities:
  - A Cloudflare-first backend for speed, reliability, and developer velocity
  - Distributed realtime from PostgreSQL to backend workflows to frontends
  - AI everything
  - Automate everything
  - Test everything

technology stack:
  - postgresql (Main database hosted on Docker at fly.io)
  - zero sync (Sync engine between Postgres, Cloudflare Durable Objects, and browsers; docs: https://zero.rocicorp.dev/docs/zero-schema)
  - cloudflare workers (microservices)
  - cloudflare workers_ai (function calling)
  - cloudflare ai_gateway (maybe?)
  - cloudflare vectorize (embeddings)
  - cloudflare r2 (unstructured data storage)
  - cloudflare images (resize, optimize, transform images from R2)
  - cloudflare queues (async tasks/workflows)
  - cloudflare hyperdrive (Postgres connection pool)
  - typescript
  - effect (All custom code/business logic: error handling, piping/workflows, tracing/logging)
  - bun (Package manager and testing framework)

code quality guidelines:
  - Rely on existing code
  - Only write new code when absolutely necessary
  - Write testable code
  - Reliability and error-free code is paramount
  - Efficiency and performance are secondary to reliability
  - Write code that is clear for both AI and humans
  - Maintain 100% type safety
  - Fix type errors until there are none
  - Type casting only allowed in justified edge cases
  - Stick to package.json dependencies
  - Only deviate from dependencies when there's significant benefit
  - Ask for clarification before proceeding with unclear tasks

code style rules:
  - Naming conventions: variables => snake_case, properties => snake_case, functions => snake_case, files => kebab-case
  - Custom types => PascalCase prefixed with "T" (e.g. TImage)
  - External dependencies => default casing
  - Comments: ai_generated => prefix with (ai)

directory specific rules:
  - src/** => use Bun as test runner, write 100% Cloudflare Workers compatible code, no Bun-specific code
  - script/** => use Bun exclusively for tests, write 100% Bun code, strictly no Node.js code

core principles:
  - Begin with foundational observations
  - Keep exploring until a solution emerges naturally from the evidence
  - Continue reasoning indefinitely when uncertain
  - Question every assumption and inference
  - Acknowledge and explore dead ends
  - Frequently revise and backtrack as needed