memory-journal-mcp 7.3.0 → 7.4.0

package/skills/python/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: python
+description: |
+  Master modern Python development with production-grade tooling and idioms.
+  Use when writing Python code, configuring project structure, managing
+  dependencies with uv, linting with ruff, adding type hints, writing pytest
+  tests, or building FastAPI/Django/Flask applications. Triggers on "Python",
+  "FastAPI", "Django", "Flask", "pytest", "uv", "ruff", "pyproject.toml".
+---
+
+# Python Engineering Standards
+
+This skill codifies 2026 Python best practices — modern tooling (`uv`, `ruff`), strict typing, and idiomatic patterns that produce maintainable, performant code.
+
+## 1. Project Setup & Structure
+
+### Tooling: `uv` (Not pip/pipenv/poetry)
+
+`uv` is the standard package manager for Python in 2026. It replaces pip, pipenv, and poetry with a single, fast Rust binary.
+
+```bash
+uv init <project-name>       # Initialize a new project
+uv add <package>              # Add a dependency
+uv add --dev <package>        # Add a dev dependency
+uv run <command>              # Run a command in the project's venv
+uv sync                      # Install all deps from uv.lock
+uv python install 3.13        # Install a specific Python version
+```
+
+- **ALWAYS** commit both `pyproject.toml` AND `uv.lock` to version control.
+- **NEVER** use `requirements.txt` for new projects — it is a legacy pattern.
+- **NEVER** use `pip install` directly — use `uv add` to keep the lock file in sync.
+
+### Directory Layout: `src/` Layout
+
+```
+my-project/
+├── .python-version          # Pin Python version (e.g., 3.13)
+├── pyproject.toml           # Single source of truth for config
+├── uv.lock                  # Deterministic lock file
+├── src/
+│   └── my_package/
+│       ├── __init__.py
+│       ├── main.py
+│       └── models.py
+└── tests/
+    ├── __init__.py
+    ├── conftest.py          # Shared fixtures
+    └── test_main.py
+```
+
+- **Use `src/` layout** for packages and production apps — it prevents tests from accidentally importing the local source instead of the installed package.
+- **Group by domain**, not file type — prefer `users/`, `billing/`, `auth/` over `models/`, `utils/`, `services/`.
+- **Use `kebab-case`** for directory names, `snake_case` for Python modules.
+
+### `pyproject.toml` Configuration (PEP 621)
+
+```toml
+[project]
+name = "my-package"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.8", "mypy>=1.13"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+```
+
+## 2. Type Hints (Mandatory)
+
+Type hints are **not optional** — they are foundational design tools.
+
+### Rules
+
+- **Use built-in generics** (Python 3.9+): `list[str]`, `dict[str, int]`, `tuple[int, ...]`
+- **Use union syntax** (Python 3.10+): `str | None` instead of `Optional[str]`
+- **Avoid `Any`** — use `object`, `Unknown`, or narrow with type guards
+- **Use `TypedDict`** for dict-shaped data with known keys
+- **Use `Protocol`** for structural subtyping instead of ABCs
+- **Run static analysis**: `mypy --strict` or `pyright`
+
+### Examples
+
+```python
+# ✅ Good
+def get_user(user_id: int) -> User | None:
+    ...
+
+class Config(TypedDict):
+    host: str
+    port: int
+    debug: bool
+
+# ❌ Bad
+def get_user(user_id):  # Missing type hints
+    ...
+
+def process(data: Any):  # Untyped escape hatch
+    ...
+```
+
+## 3. Code Quality: `ruff`
+
+Ruff is the **all-in-one** linter and formatter for Python. It replaces Flake8, Black, isort, pyupgrade, and more.
+
+```bash
+ruff check --fix .    # Lint with auto-fix
+ruff format .         # Format (replaces Black)
+```
+
+### Configuration in `pyproject.toml`
+
+```toml
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # bugbear
+    "SIM",  # simplify
+    "RUF",  # ruff-specific
+]
+```
+
+- **NEVER** use `# noqa` to suppress linter errors unless the suppression is explicitly justified by a comment explaining _why_.
+- **NEVER** use `# type: ignore` — fix the type error or use a proper type guard.
+
+## 4. Error Handling
+
+### Patterns
+
+- **Use specific exception types** — never catch bare `except:` or `except Exception:`
+- **Create custom exceptions** inheriting from a base project exception
+- **Use `from` for exception chaining**: `raise ValueError("msg") from original_error`
+- **Never swallow exceptions silently** — at minimum, log them
+
+```python
+# ✅ Good
+class AppError(Exception):
+    """Base exception for the application."""
+
+class NotFoundError(AppError):
+    """Raised when a resource is not found."""
+
+try:
+    user = get_user(user_id)
+except DatabaseError as e:
+    raise NotFoundError(f"User {user_id} not found") from e
+
+# ❌ Bad
+try:
+    user = get_user(user_id)
+except:           # Bare except — catches SystemExit, KeyboardInterrupt
+    pass          # Silently swallowed
+```
+
+## 5. Testing with `pytest`
+
+### Structure
+
+- **AAA pattern**: Arrange, Act, Assert — one concern per test
+- **Use fixtures** for setup/teardown, not classes with `setUp()`/`tearDown()`
+- **Use `conftest.py`** for shared fixtures across test modules
+- **Use `@pytest.mark.parametrize`** for data-driven tests
+
+```python
+@pytest.fixture
+def client(tmp_path: Path) -> TestClient:
+    """Create a test client with a temporary database."""
+    app = create_app(db_path=tmp_path / "test.db")
+    return TestClient(app)
+
+@pytest.mark.parametrize("status_code,expected", [
+    (200, True),
+    (404, False),
+    (500, False),
+])
+def test_is_success(status_code: int, expected: bool) -> None:
+    assert is_success(status_code) == expected
+```
+
+### Running Tests
+
+```bash
+uv run pytest                           # Run all tests
+uv run pytest tests/test_main.py        # Run specific file
+uv run pytest -k "test_user"            # Run by pattern
+uv run pytest --cov=src --cov-report=term-missing  # Coverage
+```
+
+## 6. Async & Concurrency
+
+- **Use `asyncio`** for I/O-bound concurrency (HTTP calls, DB queries)
+- **Use `async def` / `await`** — never mix sync and async code paths
+- **Use `asyncio.TaskGroup`** (Python 3.11+) for structured concurrency
+- **Use `httpx`** (async-native) instead of `requests` for HTTP clients
+
+```python
+async with asyncio.TaskGroup() as tg:
+    task1 = tg.create_task(fetch_user(user_id))
+    task2 = tg.create_task(fetch_orders(user_id))
+# Both tasks complete here — exceptions propagate cleanly
+```
+
+## 7. Data Validation: Pydantic v2
+
+- **Use Pydantic models** at system boundaries (API requests, config files, DB results)
+- **Never trust external input** — validate with `model_validate()`, not dict access
+- **Use `Field()` validators** for constraints, not manual `if` checks
+
+```python
+from pydantic import BaseModel, Field
+
+class CreateUserRequest(BaseModel):
+    name: str = Field(min_length=1, max_length=100)
+    email: str = Field(pattern=r"^[\w.-]+@[\w.-]+\.\w+$")
+    age: int = Field(ge=0, le=150)
+```
+
+## 8. Anti-Patterns (Never Do These)
+
+| Anti-Pattern                         | Why It's Wrong                     | Do This Instead              |
+| ------------------------------------ | ---------------------------------- | ---------------------------- |
+| `import *`                           | Pollutes namespace, breaks tooling | Explicit imports             |
+| Mutable default args (`def f(x=[])`) | Shared across calls                | Use `None` + assign          |
+| Global mutable state                 | Thread-unsafe, untestable          | Dependency injection         |
+| `os.path` for path manipulation      | Platform-inconsistent              | Use `pathlib.Path`           |
+| `print()` for logging                | No levels, no rotation             | Use `logging` or `structlog` |
+| `== None` / `== True`                | Wrong semantics                    | `is None` / `is True`        |
+
+## 9. Web Frameworks Quick Reference
+
+| Framework   | Best For                     | Key Pattern                                               |
+| ----------- | ---------------------------- | --------------------------------------------------------- |
+| **FastAPI** | REST APIs, async, auto-docs  | Pydantic models, dependency injection, `async def` routes |
+| **Django**  | Full-stack, admin, ORM       | Models → Views → Templates, `manage.py`, migrations       |
+| **Flask**   | Lightweight APIs, prototypes | Blueprints, application factory pattern                   |

package/skills/tailwind-css/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: tailwind-css
+description: |
+  Master Tailwind CSS v4 with its CSS-first configuration paradigm. Use when
+  writing utility classes, configuring design tokens via @theme, implementing
+  dark mode, migrating from v3, or integrating with React/Vue/Svelte. Triggers
+  on "Tailwind", "utility CSS", "Tailwind v4", "@theme", "dark mode classes",
+  "responsive design", "Tailwind migration".
+---
+
+# Tailwind CSS v4 Engineering Standards
+
+This skill codifies Tailwind CSS v4's **CSS-first architecture** — the paradigm shift from JavaScript configuration to native CSS-based theming and customization.
+
+## 1. Core Paradigm: CSS-First Configuration
+
+### Entry Point
+
+Replace all legacy directives with a single import:
+
+```css
+/* main.css */
+@import 'tailwindcss';
+```
+
+- **NEVER** use `@tailwind base; @tailwind components; @tailwind utilities;` — this is v3 syntax
+- **No `tailwind.config.js` needed** for most projects — CSS is the single source of truth
+- Use `@config "./tailwind.config.js"` only for legacy migration or PostCSS plugin compatibility
+
+### The `@theme` Directive
+
+All design tokens are defined directly in CSS:
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  /* Colors */
+  --color-primary-50: #eff6ff;
+  --color-primary-500: #3b82f6;
+  --color-primary-900: #1e3a5a;
+
+  /* Typography */
+  --font-display: 'Inter', sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+
+  /* Spacing */
+  --spacing-container: 1200px;
+
+  /* Border Radius */
+  --radius-card: 0.75rem;
+}
+```
+
+- Tailwind **automatically generates utility classes** from `@theme` variables
+- `--color-primary-500` → `bg-primary-500`, `text-primary-500`, `border-primary-500`
+- `--font-display` → `font-display`
+- Tokens are native CSS variables — inspectable in browser DevTools
+
+## 2. Dark Mode
+
+### Configuration (v4 Pattern)
+
+```css
+/* Class-based dark mode (most common) */
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+### Usage in HTML
+
+```html
+<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
+  <h1 class="text-primary-500 dark:text-primary-300">Title</h1>
+</div>
+```
+
+### System Preference (Default)
+
+By default, Tailwind v4 respects `prefers-color-scheme`. If you want manual class toggle control, use `@custom-variant dark` as shown above.
+
+### Toggle Implementation
+
+```javascript
+// Toggle dark mode via JavaScript
+document.documentElement.classList.toggle('dark')
+
+// Or persist to localStorage
+const isDark = localStorage.getItem('theme') === 'dark'
+document.documentElement.classList.toggle('dark', isDark)
+```
+
+## 3. Responsive Design
+
+### Mobile-First Breakpoints
+
+Tailwind uses a **mobile-first** approach — unprefixed utilities apply to all screens, prefixed utilities apply at that breakpoint and above.
+
+```html
+<!-- Full width on mobile, half on md, third on lg -->
+<div class="w-full md:w-1/2 lg:w-1/3">...</div>
+
+<!-- Stack on mobile, row on sm+ -->
+<div class="flex flex-col sm:flex-row gap-4">...</div>
+```
+
+### Default Breakpoints
+
+| Prefix | Min Width | Target        |
+| ------ | --------- | ------------- |
+| `sm`   | 640px     | Small tablets |
+| `md`   | 768px     | Tablets       |
+| `lg`   | 1024px    | Laptops       |
+| `xl`   | 1280px    | Desktops      |
+| `2xl`  | 1536px    | Large screens |
+
+### Custom Breakpoints
+
+```css
+@theme {
+  --breakpoint-xs: 475px;
+  --breakpoint-3xl: 1920px;
+}
+```
+
+## 4. Component Patterns
+
+### Buttons
+
+```html
+<button
+  class="
+  inline-flex items-center justify-center
+  rounded-lg px-4 py-2
+  bg-primary-500 text-white font-medium
+  hover:bg-primary-600
+  focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500
+  active:scale-[0.98]
+  disabled:opacity-50 disabled:cursor-not-allowed
+  transition-all duration-150
+"
+>
+  Click me
+</button>
+```
+
+### Cards
+
+```html
+<article
+  class="
+  rounded-xl border border-gray-200 dark:border-gray-700
+  bg-white dark:bg-gray-800
+  p-6 shadow-sm
+  hover:shadow-md transition-shadow
+"
+>
+  <h3 class="text-lg font-semibold text-gray-900 dark:text-white">Title</h3>
+  <p class="mt-2 text-gray-600 dark:text-gray-400">Description text.</p>
+</article>
+```
+
+### Custom Component Classes
+
+```css
+@layer components {
+  .btn-primary {
+    @apply inline-flex items-center justify-center rounded-lg px-4 py-2
+           bg-primary-500 text-white font-medium
+           hover:bg-primary-600 transition-colors;
+  }
+}
+```
+
+- **Use `@layer components`** for reusable component styles
+- **Prefer utility classes inline** for one-off styling
+- **Use `@apply` sparingly** — only for highly-repeated patterns
+
+## 5. Animations & Transitions
+
+### Built-in Transitions
+
+```html
+<!-- Smooth hover effect -->
+<div class="transition-all duration-300 ease-in-out hover:scale-105">
+  <!-- Color transitions only -->
+  <a class="transition-colors duration-150 text-gray-500 hover:text-primary-500"></a>
+</div>
+```
+
+### Custom Animations
+
+```css
+@theme {
+  --animate-fade-in: fade-in 0.3s ease-out;
+  --animate-slide-up: slide-up 0.4s ease-out;
+}
+
+@keyframes fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes slide-up {
+  from {
+    opacity: 0;
+    transform: translateY(1rem);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+```
+
+Usage: `class="animate-fade-in"` or `class="animate-slide-up"`
+
+## 6. Migration from v3 to v4
+
+### Step-by-Step
+
+1. **Update package**: `pnpm add -D tailwindcss@latest`
+2. **Replace CSS entry point**:
+   - Remove: `@tailwind base; @tailwind components; @tailwind utilities;`
+   - Add: `@import "tailwindcss";`
+3. **Migrate `tailwind.config.js`** → `@theme` block in CSS
+4. **Update dark mode**: Replace `darkMode: "class"` config with `@custom-variant dark`
+5. **Check defaults**: Some defaults changed (e.g., border colors). Verify visually.
+6. **Remove PostCSS plugins** if no longer needed (v4 has its own engine)
+
+### Key Breaking Changes
+
+| v3                                    | v4                           |
+| ------------------------------------- | ---------------------------- |
+| `tailwind.config.js`                  | `@theme` in CSS              |
+| `darkMode: "class"`                   | `@custom-variant dark (...)` |
+| `@tailwind base/components/utilities` | `@import "tailwindcss"`      |
+| `theme.extend.colors`                 | `--color-*` in `@theme`      |
+| `theme.extend.fontFamily`             | `--font-*` in `@theme`       |
+
+## 7. Anti-Patterns (Never Do These)
+
+| Anti-Pattern                                 | Why It's Wrong                                    | Do This Instead                                                  |
+| -------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------- |
+| `@apply` everywhere                          | Defeats utility-first purpose, harder to maintain | Use inline utilities; `@apply` only for highly-repeated patterns |
+| `!important` classes                         | Specificity wars, unpredictable cascade           | Use proper specificity layers                                    |
+| Arbitrary values excessively (`text-[17px]`) | Breaks design system consistency                  | Define tokens in `@theme`                                        |
+| Inline `style=` alongside utilities          | Mixed paradigms, inconsistent                     | All styling via Tailwind utilities                               |
+| Using v3 `tailwind.config.js` in v4          | Unnecessary JS dependency                         | Migrate to `@theme` in CSS                                       |
+| Not using `dark:` variants                   | Inaccessible for dark-mode users                  | Always implement dark mode                                       |
+| Ignoring mobile-first                        | Desktop-only layouts break on phones              | Design mobile-first, add breakpoints up                          |
+
+## 8. Accessibility Essentials
+
+- **Always use `focus-visible:`** for keyboard focus indicators — never remove focus outlines without replacement
+- **Ensure color contrast** — text must meet WCAG AA (4.5:1 normal, 3:1 large)
+- **Use `sr-only`** class for screen-reader-only text on icon buttons
+- **Never use `hidden`** for content that should be accessible — use `sr-only` instead
+
+```html
+<button class="p-2 rounded-lg hover:bg-gray-100 focus-visible:ring-2">
+  <svg class="size-5" aria-hidden="true">...</svg>
+  <span class="sr-only">Close menu</span>
+</button>
+```