# Vibetuner

> Vibetuner is a production-ready FastAPI project scaffolding tool that generates full-stack web applications with
> authentication, flexible database support (MongoDB or SQL), frontend, Docker deployment, and CLI tools
> pre-configured in seconds. Built by All Tuner Labs for rapid iteration and modern development.

Important notes:

- Vibetuner consists of four packages: a Python framework (`vibetuner`), a JavaScript build-deps package
  (`@alltuner/vibetuner`) which bundles tailwind, daisyui, htmx and an npm-shipped mirror of the framework's jinja
  templates (`@alltuner/vibetuner-jinja`, pulled in as a transitive — consumers don't install it directly), and a
  Copier scaffolding template
- The framework separates immutable framework code (`vibetuner` package) from your application code (`src/app/`) for
  clean updates
- In all examples, `app` refers to your project's Python package (the directory under `src/`). The actual name depends
  on your project slug (e.g., `src/myproject/` for a project named "myproject")
- HTMX is used instead of React/Vue for simplicity - server-rendered HTML with sprinkles of interactivity
- All tools are chosen for speed: uv (Python), bun (JavaScript), Granian (ASGI server), Ruff (linting)
- The project is designed to work excellently with AI coding assistants like Claude, Cursor, and ChatGPT

## Quick Start

### Prerequisites

- **Python 3.11+**: [python.org/downloads](https://www.python.org/downloads/)
- **Docker**: [docker.com/get-started](https://www.docker.com/get-started/) (for containerized development)

That's it! Vibetuner handles the rest.

### Create Your First Project

#### Using uvx (Recommended)

No installation needed:

```bash
uvx vibetuner scaffold new my-app
```

#### Install Globally

```bash
uv tool install vibetuner
vibetuner scaffold new my-app
```

#### Interactive Setup

The scaffold command will ask you:

- **Project name**: `my-app`
- **Company name**: Your company/organization
- **Author details**: Name and email
- **Features**: OAuth providers, background jobs, etc.

#### Skip Prompts

Use defaults for everything:

```bash
uvx vibetuner scaffold new my-app --defaults
```

### Start Development

```bash
cd my-app
just dev
```

For projects using SQL models (SQLModel/SQLite/PostgreSQL), create tables first:

```bash
uv run vibetuner db create-schema   # Required once before first run
just dev
```

This starts:

- Database (MongoDB or SQL, if configured)
- Redis (if background jobs enabled)
- FastAPI application with hot reload
- Frontend asset compilation

Visit `http://localhost:8000` - your app is running!

### Project Structure

```text
my-app/
├── src/app/                # Your code (edit freely)
│   ├── frontend/routes/    # Your HTTP routes
│   ├── models/             # Your database models
│   └── services/           # Your business logic
├── templates/              # Jinja2 templates
├── assets/                 # Static files
└── Dockerfile              # Production deployment
```

The `vibetuner` framework (auth, database, core services) is installed as a package dependency.

### Justfile Commands

All project management tasks use `just` (command runner). Run `just` to see all available commands.

**Development:**

```bash
just dev                     # Docker development with hot reload (recommended)
just local-dev PORT=8000     # Local development without Docker
just worker-dev              # Background worker (if background jobs enabled)
```

**Dependencies:**

```bash
just install-deps            # Install from lockfiles
just update-repo-deps        # Update root scaffolding dependencies
uv add package-name          # Add Python package
bun add package-name         # Add JavaScript package
```

**Code Formatting:**

```bash
just format                  # Format ALL code (Python, Jinja, TOML, YAML)
just format-py               # Format Python with ruff
just format-jinja            # Format Jinja templates with djlint
just format-toml             # Format TOML files with taplo
just format-yaml             # Format YAML files with dprint
```

**IMPORTANT**: Always run `ruff format .` or `just format-py` after Python changes.

**Code Linting:**

```bash
just lint                    # Lint ALL code
just lint-py                 # Lint Python with ruff
just lint-jinja              # Lint Jinja templates with djlint
just lint-md                 # Lint markdown files
just lint-toml               # Lint TOML files with taplo
just lint-yaml               # Lint YAML files with dprint
just type-check              # Type check at the repo root (template + tooling)
just type-check-py           # Type check the vibetuner-py framework code with ty
```

**Localization:**

```bash
just i18n                    # Full workflow: extract, update, compile
just extract-translations    # Extract translatable strings
just update-locale-files     # Update existing .po files
just compile-locales         # Compile .po to .mo files
just new-locale LANG         # Create new language (e.g., just new-locale es)
just i18n-fuzzy-audit        # Report fuzzy-marked entries across catalogs
```

`update-locale-files` runs `msgmerge --no-fuzzy-matching`: new strings
land with an empty `msgstr` (honest untranslated → English fallback)
instead of a wrong guess copied from a textually similar entry. The i18n
recipes also pass `--no-wrap`, keeping every `msgid`/`msgstr` on a single
line so catalogs don't drift when gettext's line-wrapping differs between
macOS and the Linux used in CI.

**CI/CD & Deployment:**

```bash
just build-dev               # Build development Docker image
just test-build-prod         # Test production build locally
just build-prod              # Build production image
just release                 # Build and release production image
just deploy-latest HOST      # Deploy to remote host
```

**Scaffolding:**

```bash
just update-scaffolding      # Update project to latest vibetuner template
just deps-scaffolding        # Update deps + scaffolding on the current branch (no PR)
just deps-scaffolding-pr     # Update deps + scaffolding in a worktree and open a PR
```

## Core Documentation

### Development Guide

#### Development Environment

Vibetuner supports two development modes:

##### Docker Development (Recommended)

Run everything in containers with hot reload:

```bash
just dev
```

This starts:

- Database (MongoDB or SQL, if configured)
- Redis (if background jobs enabled)
- FastAPI application with auto-reload
- Frontend asset compilation with watch mode

Changes to Python code, templates, and assets automatically reload.

##### Local Development

Run services locally without Docker:

```bash
# Terminal 1: Frontend assets
bun dev
# Terminal 2: Backend server
just local-dev
```

A database (MongoDB or SQL) is required if using database features. Redis is only required if background jobs are enabled.

#### Adding New Routes

Create a new file in `src/app/frontend/routes/`:

```python
# src/app/frontend/routes/blog.py
from fastapi import APIRouter
router = APIRouter(prefix="/blog", tags=["blog"])
@router.get("/")
async def list_posts():
    return {"posts": []}
```

Register in `src/app/frontend/__init__.py`:

```python
from app.frontend.routes import blog
app.include_router(blog.router)
```

**`@render` decorator** — for simple routes, eliminate `render_template()` boilerplate:

```python
from vibetuner import render

@router.get("/dashboard")
@render("dashboard.html.jinja")
async def dashboard(request: Request, user=Depends(get_current_user)) -> dict:
    return {"user": user}
```

Returns `Response` objects unchanged (escape hatch for redirects, conditional logic).

#### Adding Database Models

Create models in `src/app/models/`. The approach depends on your database choice:

##### MongoDB (Beanie ODM)

```python
# src/app/models/post.py
from beanie import Document
from pydantic import Field

class Post(Document):
    title: str
    content: str
    published: bool = Field(default=False)

    class Settings:
        name = "posts"
```

Beanie builds queries from class-level field access (`Post.title == "x"`,
`Eq(cls.author.id, user.id)`), which static checkers don't model: `ty` resolves
`Model.field` from the field's instance annotation, not as a query expression.
Most comparisons type-check, but two patterns trip a spurious `unresolved-attribute`
in `just lint`: an optional link in a query (`field: Link[X] | None` with
`cls.field.id` → `id is not defined on None`, fundamental to how `ty` treats
`X | None`, not fixable via field/alias changes), and queries inside a classmethod
on a non-`Document` (`BaseModel`) mixin. Silence on the exact line:

```python
return await cls.find_one(Eq(cls.author.id, user.id))  # ty: ignore[unresolved-attribute]
```

`ty` reports directives that stop matching (`unused-ignore-comment`), so keep the
comment on the erroring line and remove it when no longer needed.

##### SQL (SQLModel)

```python
# src/app/models/post.py
from sqlmodel import SQLModel, Field

class Post(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    title: str
    content: str
    published: bool = Field(default=False)
```

For SQL databases, create tables with: `vibetuner db create-schema`

Register models in `src/app/models/__init__.py`:

```python
from app.models.post import Post
__all__ = ["Post"]
```

The model will be automatically registered with the database on startup.

##### Soft Delete (MongoDB)

Use `DocumentWithSoftDelete` instead of `Document` to mark documents as deleted instead of removing them:

```python
from vibetuner.models import DocumentWithSoftDelete
from vibetuner.models.mixins import TimeStampMixin

class Post(DocumentWithSoftDelete, TimeStampMixin):
    title: str
    content: str

    class Settings:
        name = "posts"
```

Soft-deleted documents are automatically excluded from `find()`, `find_one()`, and `get()` queries.
Use `find_many_in_all()` to include them. `delete()` sets `deleted_at` instead of removing the document.
`hard_delete()` permanently removes it. To restore: `doc.deleted_at = None; await doc.save()`.
The CRUD factory's DELETE endpoint automatically performs a soft delete for these models.

##### Encrypted Fields (MongoDB)

Encrypt sensitive fields at rest using `EncryptedFieldsMixin` and `EncryptedStr`:

```python
from beanie import Document
from pydantic import Field
from vibetuner.models.mixins import EncryptedFieldsMixin, EncryptedStr

class ApiCredential(Document, EncryptedFieldsMixin):
    provider: str
    api_key: EncryptedStr = Field(..., description="Encrypted API key")
    token: EncryptedStr | None = Field(default=None)

    class Settings:
        name = "api_credentials"
```

Fields are transparently encrypted before database writes and decrypted on load.
Requires `FIELD_ENCRYPTION_KEY` environment variable (Fernet key). Use
`vibetuner crypto set-key` to generate a key, `vibetuner crypto rotate-key` to
rotate it.

#### Creating Templates

Add templates in `templates/`:

```html
<!-- templates/blog/list.html.jinja -->
{% extends "base/skeleton.html.jinja" %}
{% block content %}
    <div class="container mx-auto">
        <h1 class="text-3xl font-bold">Blog Posts</h1>
        <div class="grid gap-4">
            {% for post in posts %}
                <article class="card">
                    <h2>{{ post.title }}</h2>
                    <div>{{ post.content }}</div>
                </article>
            {% endfor %}
        </div>
    </div>
{% endblock %}
```

#### Skeleton Extension Points

`base/skeleton.html.jinja` exposes blocks and context variables so projects
can slot in customisations without copying the whole skeleton. Extending it
is preferable to overriding it: upstream changes (CSP nonce, theming, etc.)
flow through automatically.

**Blocks** (override in any child template):

- `extra_head_links` — after `<title>`, before `bundle.css`. For
  `<link rel="alternate">` feeds, RSS, custom meta tags.
- `extra_scripts` — after the bundled `<script>` (and optional umami). For
  per-app scripts that don't replace `bundle.js`.
- `before_main` — inside `<body>`, before `block body`. For dev banners,
  sticky overlays.
- `after_main` — inside `<body>`, after `block body`. For persistent
  mini-players, floating toolbars.

Existing blocks already there: `title`, `head`, `scripts`, `start_of_body`,
`header`, `body`, `content`, `footer`, `end_of_body`.

**Context variables** (set via `register_globals`, a context provider, or
per-render `ctx`):

- `color_scheme` — `str`, defaults to `"light"`. Sets
  `<meta name="color-scheme">` content.
- `canonical_url` — `str | None`, defaults to `None`. When set, renders
  `<link rel="canonical" href="…">`.
- `font_preloads` — `list[dict]`, defaults to `[]`. Each entry renders
  `<link rel="preload" as="font" href="…" type="…" [crossorigin="…"]>`.
  Listed before `bundle.css` so the preload scanner picks them up early.

Example: a project skeleton override that adds an RSS feed and a persistent
player without touching upstream markup:

```html
{% extends "base/skeleton.html.jinja" %}

{% block extra_head_links %}
    <link rel="alternate" type="application/rss+xml"
          title="My App" href="{{ url_for('rss').path }}" />
{% endblock extra_head_links %}

{% block after_main %}
    {% include "components/player.html.jinja" %}
{% endblock after_main %}
```

#### Built-in Template Globals

These variables are available in every template automatically:

- `request` — current Starlette `Request`
- `language` — resolved request language (e.g. `"en"`, `"ca"`)
- `DEBUG` — mirrors `settings.debug`
- `now` — `datetime.now(timezone.utc)`, timezone-aware UTC datetime
- `today` — `date.today().isoformat()`, ISO date string (e.g., `"2026-04-07"`)
- `project` — `settings.project` (`ProjectConfiguration` loaded from
  `config_vars.yaml`); use `project.project_name`, `project.company_name`,
  `project.copyright`, `project.fqdn`, etc.
- `brand` — `settings.brand` (`BrandSettings` from `BRAND_*` env vars);
  see [Brand Configuration](#brand-configuration)
- `csp_nonce` — per-request CSP nonce
- `hotreload` — dev-mode hot-reload helper

```html
<title>{{ project.project_name }}</title>
<p>Page rendered at {{ now | format_datetime }}</p>
<footer>{{ project.copyright }}</footer>
```

#### Built-in Template Filters

Vibetuner provides several built-in template filters for common formatting needs:

| Filter | Usage | Output |
|--------|-------|--------|
| `timeago` | `{{ dt \| timeago }}` | "5 minutes ago" |
| `timeago(short=True)` | `{{ dt \| timeago(short=True) }}` | "5m ago" |
| `format_date` | `{{ dt \| format_date }}` | "January 15, 2025" |
| `format_datetime` | `{{ dt \| format_datetime }}` | "January 15, 2025 at 2:30 PM" |
| `format_duration` / `duration` | `{{ seconds \| duration }}` | "5 min" or "30 sec" |

The `timeago` filter converts a datetime to a human-readable relative time string. Use `short=True` for compact
displays like "5m ago", "1d ago", "3mo ago".

Short format outputs: < 60 seconds = "just now", < 60 minutes = "Xm ago", < 24 hours = "Xh ago", < 7 days = "Xd ago",
< 30 days = "Xw ago", < 365 days = "Xmo ago", < 4 years = "Xy ago", >= 4 years = "MMM DD, YYYY".

#### Adding Custom Template Filters

Register custom Jinja2 filters via the `template_filters` dict in `VibetunerApp`:

```python
# src/app/frontend/templates.py
def uppercase(value):
    """Convert value to uppercase"""
    return str(value).upper()

def format_money(value):
    """Format value as USD currency"""
    try:
        return f"${float(value):,.2f}"
    except (ValueError, TypeError):
        return str(value)
```

```python
# src/app/tune.py
from vibetuner import VibetunerApp
from app.frontend.templates import uppercase, format_money

app = VibetunerApp(
    template_filters={
        "uppercase": uppercase,
        "money": format_money,
    },
)
```

Use in templates:

```html
<h1>{{ user.name | uppercase }}</h1>
<p>Price: {{ product.price | money }}</p>
```

**Important:** If a filter returns HTML, wrap the result with `markupsafe.Markup`
to prevent Jinja2 auto-escaping. Always escape user input inside the markup:

```python
from markupsafe import Markup, escape

def tag_badge(value: str) -> Markup:
    """Render a badge — escape user input, wrap result in Markup."""
    return Markup('<span class="badge">{}</span>').format(escape(value))
```

#### Adding Background Jobs

If you enabled background jobs, create tasks in `src/app/tasks/`:

```python
# src/app/tasks/emails.py
from vibetuner.tasks.worker import get_worker
from vibetuner.models import UserModel
from vibetuner.services.email import EmailService

worker = get_worker()

@worker.task()
async def send_welcome_email(user_id: str):
    user = await UserModel.get(user_id)
    if user:
        email_service = EmailService()
        await email_service.send_email(
            to_address=user.email,
            subject="Welcome!",
            html_body="<h1>Welcome!</h1>",
            text_body="Welcome!",
        )
    return {"status": "sent"}
```

Register tasks in `src/app/tasks/__init__.py`:

```python
# src/app/tasks/__init__.py
__all__ = ["emails"]
from . import emails  # noqa: F401
```

Queue jobs from your routes:

```python
from app.tasks.emails import send_welcome_email

@router.post("/signup")
async def signup(email: str):
    # Create user
    user = await create_user(email)

    # Queue background task
    task = await send_welcome_email.enqueue(str(user.id))

    return {"message": "Welcome email queued", "task_id": task.id}
```

#### Custom Lifespan

For custom startup/shutdown logic, create a lifespan and pass to `tune.py`:

```python
# src/app/frontend/lifespan.py
from contextlib import asynccontextmanager
from fastapi import FastAPI
from vibetuner.frontend.lifespan import base_lifespan

@asynccontextmanager
async def lifespan(app: FastAPI):
    async with base_lifespan(app):
        # Custom startup logic
        print("App starting with custom logic")
        yield
        # Custom shutdown logic
        print("App shutting down with custom logic")
```

```python
# src/app/tune.py
from vibetuner import VibetunerApp
from app.frontend.lifespan import lifespan

app = VibetunerApp(
    frontend_lifespan=lifespan,
)
```

**Worker lifespan** (different signature — takes no arguments, yields context):

```python
# src/app/tasks/lifespan.py
from contextlib import asynccontextmanager
from vibetuner.tasks.lifespan import base_lifespan

@asynccontextmanager
async def lifespan():
    async with base_lifespan() as worker_context:
        # Custom worker startup logic
        print("Worker starting with custom logic")
        yield worker_context
        # Custom worker shutdown logic
        print("Worker shutting down")
```

```python
# src/app/tune.py
from vibetuner import VibetunerApp
from app.tasks.lifespan import lifespan as worker_lifespan

app = VibetunerApp(
    worker_lifespan=worker_lifespan,
)
```

> **Note:** The frontend lifespan receives the `FastAPI` app and yields
> nothing. The worker lifespan takes no arguments and yields a `Context`
> object.

#### Working with HTMX

Vibetuner uses HTMX for interactive features without JavaScript:

```html
<!-- Load more posts -->
<button hx-get="/blog?page=2"
        hx-target="#posts"
        hx-swap="beforeend"
        class="btn btn-primary">Load More</button>
<div id="posts">
    <!-- Posts will be appended here -->
</div>
```

Server endpoint:

```python
@router.get("/blog")
async def list_posts(page: int = 1):
    posts = await Post.find().skip((page - 1) * 10).limit(10).to_list()
    return templates.TemplateResponse("blog/posts.html.jinja", {
        "posts": posts
    })
```

#### HTMX Request Detection

Every request has `request.state.htmx` available (via `starlette-htmx` middleware).
Use it to serve different responses for HTMX vs regular requests:

```python
from fastapi import Request
from starlette.responses import HTMLResponse
from vibetuner import render_template, render_template_string

@router.get("/items")
async def list_items(request: Request):
    items = await Item.find_all().to_list()
    ctx = {"items": items}

    if request.state.htmx:
        html = render_template_string("items/_list.html.jinja", request, ctx)
        return HTMLResponse(html)

    return render_template("items/list.html.jinja", request, ctx)
```

Properties: `bool(request.state.htmx)`, `.boosted`, `.target`, `.trigger`,
`.trigger_name`, `.current_url`, `.prompt`.

HTMX-only routes — use the `require_htmx` dependency from
`vibetuner.frontend.deps` to reject non-HTMX requests with a 400.

### Architecture

#### High-Level Overview

Vibetuner generates full-stack web applications with clear separation between framework code and application code.

#### Four-Package Architecture

##### 1. Scaffolding Template

**Location**: Root repository (`copier.yml`, `vibetuner-template/`)
The Copier-based template that generates new projects:

- Interactive project setup
- Configurable features (OAuth, background jobs, etc.)
- Generates complete project structure
- Updates existing projects
**Command**: `uvx vibetuner scaffold new my-app`

**2. Python Package (`vibetuner`)**

**Location**: `vibetuner-py/`
Published to PyPI, provides:

- Core framework code
- Authentication system
- Database integration (MongoDB and SQL)
- Email and storage services
- CLI commands
- Blessed dependency stack
**Install**: `uv add vibetuner`

**3. JavaScript Package (`@alltuner/vibetuner`)**

**Location**: `vibetuner-js/`
Published to npm, provides:

- Frontend build dependencies (Tailwind, esbuild, etc.)
- Version-locked with Python package
- No runtime dependencies
**Install**: `bun add @alltuner/vibetuner`

**4. Tailwind Source Package (`@alltuner/vibetuner-jinja`)**

**Location**: `vibetuner-jinja/`
Published to npm, provides:

- An npm-resolvable mirror of `vibetuner-py/src/vibetuner/templates/frontend/`
- Ships a `sources.css` containing `@source "./templates"` so tailwind
  picks up class names used by base layouts, auth pages, the debug
  toolbar, etc. — without shelling out to Python at frontend build time
- Pulled in transitively by `@alltuner/vibetuner`. Scaffolded projects'
  `config.css` does `@import "@alltuner/vibetuner/core.css"`, which
  in turn imports this package's `sources.css`. Consumer projects do
  not install it directly
- The template mirror is generated by the package's `prepare` lifecycle
  hook (no manual sync required when developing in the monorepo);
  registry consumers receive a tarball with the templates already baked
  in
- Version-locked with the Python and JS packages
**Install**: ridden along with `@alltuner/vibetuner` (no direct install
in consumer projects)

#### Request Flow

##### 1. HTTP Request

```text
Client → Nginx/Caddy → FastAPI (Granian) → Route Handler
```

##### 2. Route Handler

```python
# src/app/frontend/routes/blog.py
@router.get("/blog/{post_id}")
async def view_post(post_id: str):
    post = await Post.get(post_id)
    return templates.TemplateResponse("blog/post.html.jinja", {
        "post": post
    })
```

##### 3. Database Query

```text
# MongoDB
Route → Beanie ODM → Motor (async) → MongoDB

# SQL
Route → SQLModel → SQLAlchemy (async) → PostgreSQL/MySQL/SQLite
```

##### 4. Template Rendering

```text
Jinja2 Template → HTML with HTMX → Client
```

##### 5. HTMX Interaction

```text
User Action → HTMX Request → FastAPI → Partial HTML → Update DOM
```

### Tech Stack

#### Backend Stack

##### FastAPI

**Why:** Modern, fast, async-first Python web framework.

- Automatic API documentation (OpenAPI/Swagger)
- Async/await support throughout
- Pydantic integration for validation
- Type hints and IDE support
- High performance (comparable to Node.js/Go)

#### Database Options

Vibetuner supports multiple database backends. All are optional - choose what fits your project.

##### MongoDB + Beanie ODM

**Why:** Flexible document database for rapid prototyping.

- Schema flexibility during rapid development
- Pydantic models are database models
- Type-safe async operations
- Automatic validation
- Horizontal scaling with sharding

##### SQLModel + SQLAlchemy

**Why:** SQL databases when you need relational data.

- PostgreSQL, MySQL, MariaDB, SQLite support
- Pydantic + SQLAlchemy combined
- Type-safe async operations
- Full SQL power when needed
- CLI command: `vibetuner db create-schema`

##### Granian

**Why:** High-performance ASGI server written in Rust.

- Faster than Uvicorn/Gunicorn
- Lower memory footprint
- Built-in process management
- Hot reload in development

#### Frontend Stack

##### HTMX

**Why:** Interactivity without complex JavaScript.

- Server-rendered HTML with dynamic updates
- Progressive enhancement
- Minimal client-side complexity
- Works with any backend
- Small footprint (~14kb)

##### Tailwind CSS

**Why:** Utility-first CSS framework.

- Rapid UI development
- No naming conventions needed
- Automatic purging of unused CSS
- Responsive design made simple
- Customizable design system

##### DaisyUI

**Why:** Beautiful Tailwind CSS components.

- Pre-built components
- Theming support
- No JavaScript required
- Semantic class names
- Accessibility built-in

##### Jinja2

**Why:** Powerful template engine for Python.

- Template inheritance
- Macros for reusable components
- Filters and functions
- i18n integration
- Sandboxed execution

#### Development Tools

##### uv

**Why:** Extremely fast Python package manager.

- 10-100x faster than pip
- Reliable dependency resolution
- Compatible with pip/requirements.txt
- Built in Rust

##### bun

**Why:** Fast all-in-one JavaScript runtime and toolkit.

- 2-10x faster than npm/pnpm
- Built-in bundler, transpiler, test runner
- Drop-in Node.js replacement
- Native TypeScript support

##### just

**Why:** Command runner (better Make).

- Simple syntax
- Cross-platform
- Environment variable support
- Recipe dependencies

### Authentication

#### Overview

Vibetuner includes:

- **OAuth Authentication**: Google, GitHub, and more via Authlib
- **Magic Link Authentication**: Passwordless email-based login
- **Session Management**: Secure cookie-based sessions
- **User Model**: Pre-configured with OAuth account linking

#### OAuth Setup

##### Google OAuth

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing
3. Enable Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URI: `http://localhost:8000/auth/google/callback`

Add to `.env`:

```bash
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
```

##### GitHub OAuth

1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Create a new OAuth App
3. Set callback URL: `http://localhost:8000/auth/github/callback`

Add to `.env`:

```bash
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
```

#### Magic Link Authentication

Magic links provide passwordless authentication via email.

##### Configuration

Magic links are enabled by default. Configure email settings:

```bash
# .env
# Option A: Resend (recommended)
MAIL_RESEND_API_KEY=re_xxxxxxxxxxxx

# Option B: Mailjet
# MAIL_MAILJET_API_KEY=your-api-key
# MAIL_MAILJET_API_SECRET=your-api-secret

# Option C: Cloudflare Email Service (public beta)
# MAIL_CLOUDFLARE_API_TOKEN=cf-token
# MAIL_CLOUDFLARE_ACCOUNT_ID=your-account-id

FROM_EMAIL=noreply@example.com
```

When multiple providers are configured, auto-detection prefers Resend, then
Mailjet, then Cloudflare. Set `MAIL_PROVIDER=cloudflare` (or `resend` /
`mailjet`) to pick explicitly.

##### Resend rate limits and quota

Resend caps sends at 5 requests/second per team and enforces a monthly quota.
When a send exceeds either limit, Resend returns HTTP 429 and the provider
raises a `RateLimitError` — the send fails loudly rather than silently. The
framework does **not** retry or queue these; handle bursts upstream (for
example, by sending mail from a background task) if you expect to approach
5 req/s. On every send the provider logs Resend's `ratelimit-*` and
`x-resend-monthly-quota` response headers at `DEBUG`, and logs a `WARNING` with
those headers when a `RateLimitError` is raised.

##### How It Works

1. User enters email address
2. System sends email with unique token
3. User clicks link in email
4. System validates token and logs user in
5. Session created

##### Custom OAuth Providers

Add any OAuth provider using `custom_oauth_providers` in `tune.py`:

```python
from vibetuner import VibetunerApp
from vibetuner.models.oauth import OauthProviderModel

app = VibetunerApp(
    custom_oauth_providers={
        "linkedin": OauthProviderModel(
            identifier="sub",
            params={
                "authorize_url": "https://www.linkedin.com/oauth/v2/authorization",
                "access_token_url": "https://www.linkedin.com/oauth/v2/accessToken",
                "userinfo_endpoint": "https://api.linkedin.com/v2/userinfo",
            },
            scopes=["openid", "profile", "email"],
            config={
                "LINKEDIN_CLIENT_ID": "your-client-id",
                "LINKEDIN_CLIENT_SECRET": "your-client-secret",
            },
        ),
    },
)
```

`OauthProviderModel` fields: `identifier` (unique user ID field), `params` (endpoint URLs),
`scopes` (list of OAuth scopes), `client_kwargs` (extra client settings), `config` (credentials), `compliance_fix`
(optional Authlib compliance fix callback for providers that deviate from the OAuth spec),
`login_routes` (bool, default `True`; set to `False` to register a provider for credential
management only without creating login/callback routes, useful for account linking flows).

##### Compliance Fixes

Some providers need response patching before Authlib can parse them. Pass a
`compliance_fix` callable to `OauthProviderModel`:

```python
def strip_id_token(session, token):
    token.pop("id_token", None)
    return token

OauthProviderModel(
    ...,
    compliance_fix=strip_id_token,
)
```

The fix is applied to both env-var-based and database-backed OAuth apps using
the same provider.

##### Database-Backed OAuth Apps

For multiple sets of credentials per provider (e.g., different LinkedIn apps for
different organizations), use `OAuthProviderAppModel`:

```python
from vibetuner.models.oauth_app import OAuthProviderAppModel

app = OAuthProviderAppModel(
    provider="linkedin",
    name="Acme Corp",
    client_id="app-specific-id",
    client_secret="app-specific-secret",
    scopes=["openid", "profile", "email", "w_member_social"],
)
await app.insert()
```

Fields: `provider`, `name`, `client_id`, `client_secret`, `external_app_id` (optional),
`scopes` (overrides provider defaults when non-empty), `capabilities`, `is_active`,
`metadata`.

Use `resolve_oauth_client` to resolve the correct Authlib client:

```python
from vibetuner.frontend.oauth import resolve_oauth_client

client_name = await resolve_oauth_client("linkedin", app_id="6801...")
```

The built-in login and callback routes accept an optional `app_id` query parameter
that flows through this resolution automatically. Active database-backed apps
appear on the login page as additional sign-in buttons (e.g., "Continue with
Google · Acme Corp") alongside env-var providers, for any registered provider
with `login_routes=True`. The provider must be registered via env-var
credentials for its login route to exist; DB-backed apps for unregistered
providers will not appear on the login page.

#### Protecting Routes

##### Require Authentication

Use the `@require_auth` decorator:

```python
from vibetuner.frontend.auth import require_auth
@router.get("/dashboard")
@require_auth
async def dashboard(request: Request):
    user = request.state.user
    return templates.TemplateResponse("dashboard.html.jinja", {
        "user": user
    })
```

##### Optional Authentication

Access user if authenticated, but don't require it:

```python
@router.get("/")
async def home(request: Request):
    user = getattr(request.state, "user", None)
    return templates.TemplateResponse("home.html.jinja", {
        "user": user
    })
```

### CRUD Factory

Vibetuner includes a CRUD route factory that generates list, create, read, update,
and delete endpoints for Beanie Document models with one function call.

```python
from vibetuner.crud import create_crud_routes, Operation
from app.models import Post

# Generate all CRUD routes
post_routes = create_crud_routes(
    Post,
    prefix="/api/posts",
    tags=["posts"],
    sortable_fields=["created_at", "title"],
    filterable_fields=["status", "author_id"],
    searchable_fields=["title", "content"],
    page_size=25,
    max_page_size=100,
)
```

Register the router in `tune.py`:

```python
app = VibetunerApp(routes=[post_routes])
```

**Generated endpoints:**

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/posts` | List with pagination, filtering, sorting, search |
| POST | `/api/posts` | Create a new document |
| GET | `/api/posts/{item_id}` | Read a single document |
| PATCH | `/api/posts/{item_id}` | Update a document (partial) |
| DELETE | `/api/posts/{item_id}` | Delete a document |

**Query parameters for list:**

- `offset` / `limit` — Pagination (default page size: 25)
- `sort` — Comma-separated fields, prefix with `-` for descending (e.g., `?sort=-created_at`)
- `search` — Text search across searchable fields (case-insensitive regex)
- `fields` — Comma-separated field names to include in response
- Any filterable field as a query param (e.g., `?status=published`)

**Limiting operations:**

```python
# Only generate list and read (no create/update/delete)
post_routes = create_crud_routes(
    Post,
    operations={Operation.LIST, Operation.READ},
)
```

**Custom schemas and hooks:**

```python
from pydantic import BaseModel

class PostCreate(BaseModel):
    title: str
    content: str

class PostResponse(BaseModel):
    id: str
    title: str

async def before_create(data, request):
    data.author_id = request.state.user.id
    return data

post_routes = create_crud_routes(
    Post,
    create_schema=PostCreate,
    response_schema=PostResponse,
    pre_create=before_create,
    post_create=lambda doc, req: print(f"Created {doc.id}"),
    pre_update=lambda doc, data, req: data,
    post_update=lambda doc, req: None,
    pre_delete=lambda doc, req: None,
    post_delete=lambda doc, req: None,
    dependencies=[require_auth],
)
```

**Hook signatures reference:**

All hooks are async callables with these signatures:

| Hook | Signature | Returns |
|------|-----------|---------|
| `pre_create` | `async (data, request)` | Modified data or `None` |
| `post_create` | `async (doc, request)` | `None` |
| `pre_update` | `async (doc, data, request)` | Modified data or `None` |
| `post_update` | `async (doc, request)` | `None` |
| `pre_delete` | `async (doc, request)` | `None` |
| `post_delete` | `async (doc, request)` | `None` |

`pre_create` and `pre_update` can return the (modified) data object to override
input. If they return `None`, the original data is used.

### Server-Sent Events (SSE)

Vibetuner provides SSE helpers for real-time streaming with HTMX. Import from
`vibetuner.sse` (not `vibetuner.frontend.sse`).

```python
from vibetuner.sse import sse_endpoint, broadcast
```

**Channel-based endpoint (auto-subscribe):**

```python
from fastapi import APIRouter, Request
from vibetuner.sse import sse_endpoint

router = APIRouter()

@sse_endpoint("/events/notifications", channel="notifications", router=router)
async def notifications_stream(request: Request):
    pass  # channel kwarg handles everything
```

**Dynamic channel based on path params:**

```python
@sse_endpoint("/events/room/{room_id}", router=router)
async def room_stream(request: Request, room_id: str):
    return f"room:{room_id}"  # return channel name
```

**Generator-based (full control):**

```python
import asyncio

@sse_endpoint("/events/custom", router=router)
async def custom_stream(request: Request):
    while True:
        yield {"event": "tick", "data": "ping"}
        await asyncio.sleep(5)
```

**Broadcasting events:**

```python
from vibetuner.sse import broadcast

# Raw data
await broadcast("notifications", "update", data="<div>New item!</div>")

# With template rendering
await broadcast(
    "feed",
    "new-post",
    template="partials/post.html.jinja",
    request=request,
    ctx={"post": post},
)
```

SSE uses in-process channels by default. When Redis is configured, events are
automatically bridged via Redis pub/sub for multi-worker support.

SSE responses are sent with `Cache-Control: no-cache` and `X-Accel-Buffering: no`
so reverse proxies and CDNs (Caddy, nginx, Cloudflare) stream events through
immediately instead of buffering them. Without these, a proxy can hold the
response open and deliver nothing to the client until the connection closes — so
no extra proxy configuration is needed for live updates to work in production.

**HTMX client example:**

`hx-sse:connect` opens the stream. In htmx v4 a **named** event (the `event`
passed to `broadcast()`) is dispatched as a DOM event on the connecting element;
consume it with `hx-trigger="<event> from:#<id>"` to re-fetch current state. An
**unnamed** message (empty event name) is swapped into the connecting element
via its own `hx-target`/`hx-swap`. The recommended pattern broadcasts a named
event as a signal and lets a consumer fetch state:

```html
<div id="notifications-stream" hx-sse:connect="/events/notifications"></div>

<div hx-get="/notifications"
     hx-trigger="update from:#notifications-stream,
                 htmx:after:sse:connection from:#notifications-stream">
    <!-- current state; re-fetched on each event and every reconnect -->
</div>
```

```python
await broadcast("notifications", "update")  # signal; consumer re-fetches
```

**Backgrounded tabs drop events.** For `hx-sse:connect`, htmx v4 enables
`pauseOnBackground` by default: a hidden tab closes the stream and reopens it
when visible, with **no replay**, so events broadcast during the hidden window
are lost and the view goes stale until the next event or a reload. Recovering is
why the consumer above also triggers on `htmx:after:sse:connection` (fires on
every connect/reconnect) — one idempotent re-fetch restores current state. To
keep a stream live in the background instead, disable the pause per element with
`hx-config="sse.pauseOnBackground:false"` (or globally via `htmx.config.sse`).

`sse_endpoint(buffer_size=...)` enables `Last-Event-ID` replay, but event IDs are
per-process and monotonic, so replay is unreliable across multiple frontend
workers; the resync-on-reconnect trigger is the robust, worker-count-independent
answer.

### Response Caching

Cache route responses in Redis with `@cache`:

```python
from vibetuner.cache import cache

@router.get("/api/stats")
@cache(expire=60)  # cache for 60 seconds
async def get_stats(request: Request):
    return {"users": await count_users()}
```

Parameters: `expire` (TTL in seconds, default 60), `force_caching` (override
debug mode disable, default False), `vary_on` (callable for request-dependent
keys, default None).

Cache key is derived from path + sorted query params. Disabled in debug mode.
No-op if Redis is unavailable.

**Request-dependent keys with `vary_on`:**

```python
# Per-user cache
@router.get("/dashboard")
@cache(expire=120, vary_on=lambda r: str(r.state.user.id))
async def dashboard(request: Request):
    return await render_dashboard(request)
```

`vary_on` accepts `Callable[[Request], str]`. The returned string is included
in the cache key, so different values produce independent cache entries.

**Cache invalidation:**

```python
from vibetuner.cache import invalidate, invalidate_pattern

await invalidate("/api/stats")
await invalidate("/api/stats", query_params="page=1")
await invalidate_pattern("/api/*")
```

### Template Context Providers

Register static globals or dynamic context providers available in every template.

**Static globals:**

```python
from vibetuner.rendering import register_globals

register_globals({
    "site_title": "My App",
    "og_image": "/static/og.png",
})
```

**Dynamic providers (called on every render):**

```python
from vibetuner.rendering import register_context_provider

@register_context_provider
def site_context() -> dict:
    return {"site_title": settings.site_title, "year": 2025}

# Also works with parentheses
@register_context_provider()
def analytics_context() -> dict:
    return {"analytics_id": "UA-XXX"}
```

Values from providers and globals are merged into every `render_template()` call.
User-provided context in the render call takes precedence.

#### Passing user context

`render_template()`, `render_template_string()`, `render_template_stream()`,
`render_template_block()` and `render_template_blocks()` all accept the user
context dict positionally, as `ctx=`, or as `context=` (an alias for `ctx=`).

```python
render_template("home.html.jinja", request, {"hero": hero})           # positional
render_template("home.html.jinja", request, ctx={"hero": hero})       # ctx kwarg
render_template("home.html.jinja", request, context={"hero": hero})   # alias
```

Passing both `ctx=` and `context=` raises `TypeError`. Unknown kwargs (typos
like `contxt=` or anything Starlette's `TemplateResponse` doesn't recognise)
also raise `TypeError` — the signature is explicit, so a misspelled context
keyword cannot silently render with an empty context.

`render_template()` additionally accepts the response-shaping kwargs forwarded
to `TemplateResponse`: `status_code`, `headers`, `media_type`, `background`.

### Build-time Brand Palette

DaisyUI's `light` and `dark` themes are emitted by `@plugin "daisyui"`
inside `@alltuner/vibetuner/core.css`. To recolor the four DaisyUI role
colors across the whole compiled `bundle.css`, override the
`[data-theme="…"]` selectors directly in your project's `config.css`:

```css
@import "@alltuner/vibetuner/core.css";
@source "templates";
@source "assets/statics/js";

[data-theme="light"] {
  --color-primary: oklch(64% 0.21 24);
  --color-primary-content: oklch(98% 0 0);
  --color-accent: oklch(82% 0.18 95);
}

[data-theme="dark"] {
  --color-primary: oklch(64% 0.21 24);
  --color-primary-content: oklch(98% 0 0);
  --color-accent: oklch(82% 0.18 95);
}
```

DaisyUI emits a rule like
`:where(:root),:root:has(input.theme-controller[value=light]:checked),[data-theme=light] { … }`.
The override above shares specificity with the standalone
`[data-theme=light]` matcher and lands later in the file — cascade
picks it up. No consumer-side `daisyui` install is required.

**Caveat — DaisyUI theme-controller radio inputs.** If your UI relies on
DaisyUI's `<input class="theme-controller" value="light">` switcher
pattern *without* setting `data-theme` on the root element, the
matching selector is `:root:has(input.theme-controller[value=…]:checked)`
which has higher specificity than `[data-theme="…"]`. The override is
bypassed for that path. Set `data-theme="…"` on `<html>` directly to
keep the override pattern intact.

**Brand-new named themes.** DaisyUI's documented `@plugin "daisyui/theme"
{ name: "my-brand"; … }` form lets projects register entirely new
themes. It is **not** resolvable from a consumer-side `config.css` by
default: `daisyui` is a private transitive of `@alltuner/vibetuner`, so
bun's isolated linker keeps it scoped to that package only — the
consumer's `config.css` resolves modules from the project root and
fails with `Error: Can't resolve 'daisyui/theme'`. Add it explicitly:

```bash
bun add -d daisyui
bun install
```

The top-level symlink makes `@plugin "daisyui/theme"` resolvable.

For per-request runtime overrides on top of the build-time palette
(per-tenant branding), see the next section.

### Light / Dark / System Toggle

The skeleton ships a CSP-nonced **no-flash theme setter**
(`base/theme_init.html.jinja`) that runs synchronously high in `<head>`,
before `bundle.css`. It sets `data-theme` on `<html>` before first
paint, so the page never flashes the wrong theme.

State:

- `localStorage['theme']` — persisted preference (`"light"` / `"dark"`;
  absent means *system*).
- `data-theme-mode` on `<html>` — chosen mode (`system` / `light` / `dark`).
- `data-theme` on `<html>` — concrete theme DaisyUI renders. In `system`
  mode it resolves against `prefers-color-scheme` and live-updates when
  the OS theme changes.

Default mode is `system`, so a fresh visitor sees their OS preference.
The setter exposes `window.cycleTheme()`, cycling `system → light → dark`
and persisting the choice. Wire a toggle through htmx's nonced `hx-on`
path (a raw inline `onclick` would be blocked by `script-src`):

```html
<button class="btn btn-ghost btn-sm" hx-on:click="cycleTheme()">Theme</button>
```

Override just `base/theme_init.html.jinja` for different theming logic.
Projects replacing the skeleton wholesale must include it *before* the
`bundle.css` link.

### Per-Tenant Theming

Multi-tenant apps can swap DaisyUI role colors per tenant without rebuilding
`bundle.css`. The bundle stays tenant-agnostic and cached; theming happens
at request time via a small `<style>:root { ... }</style>` block injected
after the stylesheet link.

**1. Embed `TenantTheme` on your tenant document:**

```python
from beanie import Document
from pydantic import Field
from vibetuner.models import TenantTheme
from vibetuner.models.mixins import TimeStampMixin


class TenantModel(Document, TimeStampMixin):
    name: str
    slug: str
    theme: TenantTheme = Field(default_factory=TenantTheme)
```

`TenantTheme` exposes eight optional `#rrggbb` fields — `primary`,
`secondary`, `accent`, `neutral`, and their `*_content` foreground variants —
mapping to `--color-primary`, `--color-secondary`, etc. The validator
rejects anything that isn't a 7-character `#rrggbb` string.

Existing tenant documents without the field are unaffected: MongoDB is
schema-on-read, the default-constructed `TenantTheme` has all `None` fields,
and `keep_nulls=False` keeps it out of the database until a value is set.

**2. Register the opt-in provider:**

```python
from starlette.requests import Request
from vibetuner import register_tenant_theme_provider


def _tenant_from_request(request: Request):
    # Tenant should already be on request.state by upstream middleware/dep.
    return getattr(request.state, "tenant", None)


register_tenant_theme_provider(_tenant_from_request)
```

The getter must be synchronous and cheap — it runs on every render. Do DB
work in middleware. Pass `attribute="branding"` if your tenant uses a
different attribute name.

The provider is fail-soft: a getter exception, missing attribute, or a
non-`TenantTheme` value is logged and the request renders with no overrides
rather than 500ing.

**3. Template partial.** Vibetuner's `base/skeleton.html.jinja` already
includes `base/theme.html.jinja` between the bundled stylesheet link and
`{% block head %}`. The partial emits:

```html
<style nonce="{{ csp_nonce }}">:root {
    --color-primary: #009ddc;
    --color-accent: #ff8800;
}</style>
```

only when `theme_overrides` is non-empty. Apps that haven't registered the
provider see no extra markup.

If you've replaced the skeleton wholesale in your project, mirror the
include order:

```jinja
<link rel="stylesheet" href="{{ url_for('css', path='bundle.css').path }}" />
{% include "base/theme.html.jinja" %}
{% block head %}{% endblock head %}
```

DaisyUI scopes its theme via `:where(:root)` (zero specificity), so a plain
`:root { ... }` block always wins the cascade.

**Footguns:**

- **Build-time literals in custom tokens.** A `--shadow-glow-primary: 0 0
  80px rgba(0, 157, 220, 0.2)` won't follow the theme. Use
  `color-mix(in oklab, var(--color-primary) 20%, transparent)` so the
  derived token tracks the role color.
- **Hardcoded scale shades mixed into role-driven utilities.** `from-accent/70
  to-tiger-flame-700` only themes one half of the gradient. Either keep it
  role-only (`from-accent/70 to-accent/30`) or accept the scale shade as a
  brand constant.
- **Inline `<style>` without a CSP nonce.** The shipped partial sets it for
  you; if you write a custom override template, do the same with
  `{{ csp_nonce }}`.
- **Tailwind v3 raw-RGB tokens in `@theme`.** Custom palettes defined as
  `@theme { --color-brand-red: 239 68 68; }` with a
  `.bg-brand-red { background-color: rgb(var(--color-brand-red)); }`
  cascade-override work for direct utility usage but break under
  `@apply`. Tailwind v4 expands `@apply bg-brand-red` by inlining its own
  auto-generated `background-color: var(--color-brand-red)` rule (not
  the override), which resolves to the raw triplet — invalid, dropped,
  element renders transparent. Define `@theme` tokens as full color
  values (`rgb(239 68 68)` / `oklch(...)` / `#ef4444`) and drop the
  cascade-override; Tailwind v4 auto-generates `.bg-*` / `.text-*` from
  `@theme`.

**Out of scope:** per-tenant fonts. Font swapping requires `@font-face`
rules to load the binary before any `--font-display` variable can switch to
it, which is a different mechanism. Tracked in
[vibetuner#1705](https://github.com/alltuner/vibetuner/issues/1705).

### i18n Primitives

`vibetuner.i18n` exposes primitives for apps that need to override
locale detection or render language switchers without hardcoding language
lists.

#### `register_locale_resolver(getter, *, priority=0)`

Inject a custom selector at the **front** of `LocaleMiddleware`'s chain.
Resolvers receive the `HTTPConnection` and return either a locale code or
`None` to defer to the next resolver. All registered resolvers run before
the built-in chain (query param → URL prefix → user session → cookie →
`Accept-Language`). Within the registered group, lower `priority` runs
first; ties fall back to insertion order.

```python
from vibetuner.i18n import register_locale_resolver


def tenant_locale(conn):
    tenant = conn.scope.get("state", {}).get("tenant")
    return tenant.language if tenant else None


register_locale_resolver(tenant_locale)
```

The combined selector is fail-soft: a resolver that raises is logged and
the chain falls through. Resolvers must be synchronous — do DB lookups in
upstream middleware that already attached the tenant to `request.state`.

#### `set_request_language(request, code)`

Force the active language for the rest of the request. Updates **both**
the Babel context (drives `{% trans %}`) and `request.state.language`
(drives `<html lang>` and `Content-Language`) so all three stay in sync.
Use this for the late-bound case — e.g. switching to the user's preferred
language right after a session login.

```python
from vibetuner.i18n import set_request_language


@router.post("/login")
async def login(request: Request, ...):
    user = await authenticate(...)
    if user.preferred_language:
        set_request_language(request, user.preferred_language)
    ...
```

The code is normalized to lowercase and validated with
`babel.Locale.parse`; an invalid code raises `ValueError`.

#### `language_picker(display_locale=None, *, supported_languages=None)`

Returns a sorted `[{"code", "name"}, ...]` list. Names are rendered in
`display_locale` so the dropdown shows itself in the user's current
language. Browsing in Spanish gives "inglés / español / catalán";
browsing in Catalan gives "anglès / espanyol / català". When
`display_locale` is omitted, the current Babel context locale is used.

```python
from vibetuner.i18n import language_picker

picker = language_picker()  # display in current request's locale
es = language_picker(display_locale="es")  # always in Spanish
```

The function is also registered as a Jinja global so templates can call
it directly — no new context variable, no override of the existing
`supported_languages` template var (which stays a `set[str]` of codes):

```jinja
<select name="language">
    {% for entry in language_picker() %}
        <option value="{{ entry.code }}"
                {% if entry.code == language %}selected{% endif %}>
            {{ entry.name }}
        </option>
    {% endfor %}
</select>
```

Pass an explicit `display_locale` to override the default of "current
request locale": `{% for e in language_picker("es") %}` always renders
in Spanish.

The existing `locale_names` template variable (locale-independent native
names — `{"ca": "Català", "en": "English"}`) and the `supported_languages`
template variable (set of codes) are unchanged.

`locale_names` and `language_picker()` overlap but cover different cases:

- `locale_names` — each language always rendered in its own script,
  regardless of the request locale. Use for footers or chrome that must
  read the same in every locale.
- `language_picker()` — names rendered in the active (or explicit)
  display locale. Use for switchers that should render themselves in
  the user's current language.

Need native names but want a single source of truth? Call
`language_picker(code)` once per language instead of reading
`locale_names`.

#### `negotiate_accept_language(header, supported)` / `LocaleFromAcceptLanguage`

The built-in `Accept-Language` selector vibetuner installs in
`LocaleMiddleware`. It walks the header's language tags from highest to
lowest quality and returns the first that matches a supported locale,
either by full tag (`ca_ES` against supported `ca_ES`) or by language-only
subtag (`ca_ES` against supported `ca`). A higher-quality region-qualified
preference therefore wins over a lower-quality exact match:

```python
from vibetuner.i18n import negotiate_accept_language

supported = ["ca", "es", "eu", "nl", "sv", "en"]
negotiate_accept_language("ca-ES,es;q=0.9,en;q=0.8", supported)  # "ca"
negotiate_accept_language("ca-ES", supported)                    # "ca"
```

Tags with `q=0` (explicitly unacceptable) and the `*` wildcard are
skipped. `LocaleFromAcceptLanguage(supported_locales)` is the selector
wrapper; `negotiate_accept_language` is the pure function it delegates to,
exposed for direct reuse and testing.

### Framework Translation Catalogs

Vibetuner ships compiled `.mo` catalogs for its built-in templates so
consuming apps render framework strings (login page, magic-link email,
user profile, etc.) in the active locale **without** having to extract
every core msgid into their own catalog.

#### How it loads

`frontend/middleware.py` loads two sources into starlette-babel's
process-global translator at import time:

1. **Framework catalogs**:
   `vibetuner/locales/<lang>/LC_MESSAGES/messages.mo` — bundled inside
   the wheel.
2. **Project catalogs**:
   `<project>/locales/<lang>/LC_MESSAGES/messages.mo` — your app's
   own translations.

Both use the default `messages` domain, and starlette-babel's
`Translator.add_translations` merges identical (locale, domain) pairs
on subsequent loads. Because the project catalogs load second, project
translations override framework ones on collision. This means:

- New apps get a translated login page out of the box for every
  framework-supported locale (currently `en`, `ca`).
- An app that doesn't like a specific framework translation can
  redefine the msgid in its own `.po` file; the override wins at
  runtime with no need to fork the framework template.
- Unsupported locales fall back to the English msgid (gettext's
  `NullTranslations` behavior).

#### Contributing a new framework locale

Catalogs live at `vibetuner-py/src/vibetuner/locales/`. The repo's
root `justfile` provides the workflow:

```bash
# Regenerate messages.pot from the current source + templates
just extract-framework-translations

# Initialize a new locale (e.g. Spanish)
just new-framework-locale es

# Edit the new file:
#   vibetuner-py/src/vibetuner/locales/es/LC_MESSAGES/messages.po

# Merge new msgids into existing locales (new strings stay empty, no fuzzy guesses)
just update-framework-locales

# Compile every locale's .po to .mo so the wheel ships them
just compile-framework-locales

# Or run all four in sequence
just i18n-framework

# Report any fuzzy-marked entries left in the catalogs
just i18n-framework-fuzzy-audit
```

Both `.po` and `.mo` files are committed to the repo. The wheel build
(`uv build`) includes them automatically — there is no install-time
compilation step.

#### What strings get extracted

`vibetuner-py/babel.cfg` scans:

- `src/**.py` — Python source (`from starlette_babel import gettext_lazy as _`
  / `ngettext`, etc.). Today this covers the `timeago` filter variants
  in `rendering.py` and the magic-link email subject in
  `frontend/email.py`.
- `src/vibetuner/templates/**.html.jinja`,
  `src/vibetuner/templates/**.txt.jinja`, and
  `src/vibetuner/templates/**.xml.jinja` — Jinja2 `_()` calls in the
  framework's bundled templates.

If you add a new `_()` call to any framework template or to
framework Python code, re-run `just i18n-framework` so the existing
locales get the new msgid. The merge uses `msgmerge --no-fuzzy-matching`,
so new strings land with an empty `msgstr` (English falls back to the
msgid; non-English locales get a blank entry waiting for translation)
instead of a fuzzy guess copied from a similar string.

### Brand Configuration

`TenantTheme` covers in-page DaisyUI role colors, but a few surfaces are
out of reach of CSS variables:

- **Favicon meta tags** (`mask-icon`, `msapplication-TileColor`,
  `theme-color`) are read by the browser before any CSS runs.
- **PWA manifest** (`theme_color`, `background_color`) is consumed by the
  OS install UI, also before CSS.
- **Magic-link emails** render in clients (Gmail, Outlook) that strip
  `<style>` blocks and ignore CSS variables, so the button color must be
  inlined at render time.

`BrandSettings` is an app-level pydantic-settings surface that drives those
specific surfaces. It is deliberately **not** per-tenant: favicon assets
are static files served before the request hits any tenant resolver, and
the email service does not see request context. For per-tenant in-page
colors, keep using `TenantTheme`.

**Configuration via environment variables:**

```bash
# Defaults shown; all three are optional.
BRAND_PRIMARY_COLOR=#5b2333
BRAND_BROWSER_THEME_COLOR=#ffffff
BRAND_EMAIL_BUTTON_COLOR=  # falls back to BRAND_PRIMARY_COLOR when unset
```

`BRAND_PRIMARY_COLOR` drives the Safari pinned-tab `mask-icon` color,
the Windows tile color (`browserconfig.xml`), and the magic-link email
button (when `BRAND_EMAIL_BUTTON_COLOR` is unset).
`BRAND_BROWSER_THEME_COLOR` drives the mobile browser chrome
(`<meta name="theme-color">`) and the PWA manifest's `theme_color` /
`background_color`. `BRAND_EMAIL_BUTTON_COLOR` is the override slot for
when your brand button needs to differ from the favicon brand color
(e.g. for contrast on the email's white background).

**Inputs accept any pydantic-Color form:**

```bash
BRAND_PRIMARY_COLOR="#1DB954"          # hex (long or short)
BRAND_PRIMARY_COLOR="rgb(29, 185, 84)" # rgb()
BRAND_PRIMARY_COLOR="dodgerblue"       # CSS named colors
```

All values are canonicalised to long-form `#rrggbb` lowercase before
rendering. The underlying type is `HexColor`, a `pydantic_extra_types.color.Color`
subclass that pins `__str__` to `as_hex(format="long")` so HTML
interpolation is predictable (the bare `Color` type would render
`#ffffff` as the string `white`).

**Programmatic access:**

```python
from vibetuner.config import settings

settings.brand.primary_color       # HexColor("#5b2333")
settings.brand.browser_theme_color # HexColor("#ffffff")
settings.brand.email_button        # property: email_button_color or primary_color
```

`settings.brand` is exposed in every Jinja render via the shipped
`_brand_context` provider, so templates can read `{{ brand.primary_color }}`
without wiring anything up. The framework's bundled
`base/favicons.html.jinja`, `meta/site.webmanifest.jinja`, and
`meta/browserconfig.xml.jinja` already do this; the magic-link email
template receives `button_color=settings.brand.email_button` from
`send_magic_link_email()`.

The companion `_project_context` provider exposes `settings.project`
(`ProjectConfiguration` loaded from `config_vars.yaml`) under the
`project` template global, so branded chrome can reference
`{{ project.project_name }}`, `{{ project.company_name }}`,
`{{ project.copyright }}`, `{{ project.fqdn }}`, etc. without per-route
context boilerplate.

### Service Dependency Injection

Vibetuner provides FastAPI `Depends()` wrappers for built-in services:

```python
from fastapi import Depends
from vibetuner.services import (
    get_email_service,
    get_blob_service,
    get_runtime_config,
)

@router.post("/send")
async def send(email=Depends(get_email_service)):
    await email.send_email(to_address="user@example.com", ...)

@router.post("/upload")
async def upload(blobs=Depends(get_blob_service)):
    await blobs.upload(file_data, filename)

@router.get("/settings")
async def settings_page(config=Depends(get_runtime_config)):
    value = await config.get("features.dark_mode")
```

`BlobService()` falls back to `R2_DEFAULT_BUCKET_NAME` when no explicit
`default_bucket` is passed, and logs a one-time process warning naming the
resolved bucket. Watch deploy logs on first boot: if the bucket isn't yours,
the env var has leaked from another deploy and uploads will silently land in
the wrong place. Set `R2_DEFAULT_BUCKET_NAME` explicitly for the deploy, or
pass `default_bucket=...` to `BlobService()` to suppress the warning and
guarantee the bucket.

### Health Check Endpoints

Built-in health check routes are mounted at `/health`:

| Endpoint | Purpose |
|----------|---------|
| `GET /health/ping` | Liveness probe — always fast, no external calls |
| `GET /health` | Basic health with uptime. Add `?detailed=true` for service checks |
| `GET /health/ready` | Readiness probe — checks all configured services |
| `GET /health/id` | Instance identification (app name, port, PID, startup time) |

The detailed health check and readiness probe test MongoDB, Redis, S3/R2, and email
connectivity with latency measurements. Returns `"degraded"` or `"not_ready"` if
any required service is down.

### Robust Tasks (Retries & Dead Letters)

For tasks that need automatic retry with exponential backoff:

```python
from vibetuner.tasks.robust import robust_task

@robust_task(max_retries=5, backoff_base=2.0, backoff_max=600)
async def send_report(account_id: str):
    # If this raises, it retries with exponential backoff
    ...
```

**Parameters:**

- `max_retries` — Maximum attempts before giving up (default: 3)
- `backoff_base` — Base for exponential backoff: delay = base^tries (default: 2.0)
- `backoff_max` — Maximum backoff delay in seconds (default: 300)
- `timeout` — Task timeout (forwarded to Streaq)
- `on_failure` — Callback on permanent failure: `(task_name, task_id, exception)`

After all retries are exhausted, the task is saved to the `dead_letters` MongoDB
collection as a `DeadLetterModel` document with task name, error details, and
try count.

### Streaq Task Queue UI

When background workers are configured, Vibetuner automatically mounts the Streaq
task queue UI at `/debug/tasks`. This provides a web interface for monitoring
queued, running, and completed tasks. Access is restricted by the same debug
access check used for other debug routes.

`/debug/tasks/queue` and `/debug/tasks/workers` enumerate Redis keys with `SCAN`,
which can hang on a shared or large Redis. Both routes are bounded by a 5-second
request timeout; on expiry the server renders a "Task queue unavailable" page
listing the things to check (worker running? Redis reachable? installed `streaq`
package compatible with this vibetuner version?) with a retry link back to
`/debug/tasks/`. Clients that send `Accept: application/json` get a structured
`{"error": "streaq_debug_timeout", "detail": ...}` payload instead. The
`/debug/tasks/cron` view is not affected.

### `vibetuner doctor`

A diagnostic CLI command that validates your project setup:

```bash
vibetuner doctor
```

Checks performed:

- **Project structure** — root directory, `.copier-answers.yml`, `.env`, `src/` layout
- **App configuration** — `tune.py` loads without errors
- **Environment** — environment mode, SESSION_KEY
- **Service connectivity** — MongoDB, Redis, R2/S3 reachability
- **Models** — registered Beanie models
- **Templates** — template directory exists, basic syntax checks
- **Dependencies** — vibetuner, FastAPI, Beanie, Granian versions
- **Ports** — 8000 (frontend) and 11111 (worker UI) availability

Output uses colored status icons and a summary table. Exits with code 1 if
any errors are found.

### Config Decorators and ConfigGroup

In addition to `register_config_value()`, you can use decorators and classes:

**`@config_value` decorator:**

```python
from vibetuner.runtime_config import config_value

@config_value("features.dark_mode", value_type="bool", category="features")
def dark_mode() -> bool:
    return False  # default value

# Later, in an async context:
enabled = await dark_mode()
```

**`ConfigGroup` class:**

```python
from vibetuner.runtime_config import ConfigGroup, ConfigField

class FeatureFlags(ConfigGroup, category="features"):
    dark_mode = ConfigField(
        default=False, value_type="bool", description="Enable dark mode"
    )
    max_items = ConfigField(
        default=50, value_type="int", description="Max items per page"
    )

# Later:
enabled = await FeatureFlags.dark_mode
max_items = await FeatureFlags.max_items
```

All registered config values are viewable and editable at `/debug/config`.

### Testing Utilities

Vibetuner provides pytest fixtures for testing your application. Install the
plugin by adding `vibetuner` to your test dependencies — fixtures are
auto-discovered.

**Available fixtures:**

| Fixture | Description |
|---------|-------------|
| `vibetuner_client` | Async HTTP test client with full middleware |
| `vibetuner_app` | The FastAPI app instance (override for custom apps) |
| `vibetuner_db` | Session-scoped MongoDB DB on `TEST_MONGODB_URL` (falls back to `MONGODB_URL`); collections truncated per test |
| _(autouse)_ | Session-scoped fixture points Redis (rate limiter, cache, pub/sub) at `TEST_REDIS_URL` (falls back to `REDIS_URL`) |
| `mock_auth` | Mock authentication without real sessions |
| `mock_tasks` | Mock background tasks without Redis |
| `override_config` | Override RuntimeConfig values with auto-cleanup |

**Example test:**

```python
import pytest
from unittest.mock import patch

@pytest.mark.asyncio
async def test_dashboard(vibetuner_client, mock_auth):
    mock_auth.login(name="Alice", email="alice@example.com")
    resp = await vibetuner_client.get("/dashboard")
    assert resp.status_code == 200

@pytest.mark.asyncio
async def test_signup_sends_email(vibetuner_client, mock_tasks):
    with patch(
        "app.tasks.emails.send_welcome_email",
        mock_tasks.send_welcome_email,
    ):
        resp = await vibetuner_client.post("/signup", data={...})
    assert mock_tasks.send_welcome_email.enqueue.called

@pytest.mark.asyncio
async def test_feature_flag(override_config):
    await override_config("features.dark_mode", True)
    from vibetuner.runtime_config import RuntimeConfig
    value = await RuntimeConfig.get("features.dark_mode")
    assert value is True
```

**Running tests against a local Mongo:**

The `vibetuner_db` fixture creates a uniquely-named throwaway database on the
configured Mongo *server* and builds indexes there once per session. It targets
the server pointed at by `MONGODB_URL` unless `TEST_MONGODB_URL` is set, in which
case that wins. So if your `.env` points `MONGODB_URL` at a remote/production
cluster, set `TEST_MONGODB_URL` to a local Mongo to keep the suite fast and off
prod infrastructure — no per-invocation env juggling:

```bash
# .env (or .env.local) — prod stays for the app, tests use local Mongo
MONGODB_URL=mongodb://prod-cluster.internal:27017/
TEST_MONGODB_URL=mongodb://localhost:27017/
```

```bash
# Or spin up a throwaway local Mongo just for the suite
docker run -d --rm -p 27017:27017 mongo:7
TEST_MONGODB_URL=mongodb://localhost:27017/ pytest
```

The session start logs the resolved server and throwaway database name, so it is
always obvious where the test database is being created. The suite is skipped
entirely when neither `TEST_MONGODB_URL` nor `MONGODB_URL` is set.

**Running tests against a local Redis:**

Redis follows the same precedent. A session-scoped autouse fixture overrides
`settings.redis_url` with `TEST_REDIS_URL` when set, so the rate limiter,
response cache, pub/sub, and the shared Redis client all target the test Redis.
Without `TEST_REDIS_URL` they fall back to `REDIS_URL`, leaving existing behavior
unchanged. Pointing `REDIS_URL` at a remote/production Redis makes every request
through `vibetuner_client` pay round-trip latency on rate-limit and cache lookups,
so set `TEST_REDIS_URL` to a local Redis to keep the suite fast and off prod:

```bash
# .env (or .env.local) — prod stays for the app, tests use local Redis
REDIS_URL=redis://prod-cache.internal:6379/0
TEST_REDIS_URL=redis://localhost:6379/0
```

```bash
# Or spin up a throwaway local Redis just for the suite
docker run -d --rm -p 6379:6379 redis:7
TEST_REDIS_URL=redis://localhost:6379/0 pytest
```

### Default Language Configuration

Set the default language and supported languages in your project settings:

```bash
# .env or project config
DEFAULT_LANGUAGE=en
SUPPORTED_LANGUAGES=["es","fr","ca"]
```

The `default_language` setting (defaults to `"en"`) controls the locale used when
no language is detected from the request. It affects template rendering,
i18n middleware, and hreflang tag generation.

### Centralized Error Messages

When a service is not configured (MongoDB, Redis, S3, email), vibetuner displays
actionable error messages with:

- The exact `.env` variables needed
- Example values
- Docker commands for local development
- Links to documentation
- Hints for disabling the service if not needed

These errors are displayed as rich console panels via `vibetuner.services.errors`.

### Security Headers and CSP Nonce

`SecurityHeadersMiddleware` sets security headers and generates a Content
Security Policy with a unique nonce per request.

**Script tags** get the nonce auto-injected by the middleware. Do NOT add
`nonce=` attributes to `<script>` tags manually:

```html
<!-- Correct — nonce added automatically -->
<script src="/static/app.js"></script>

<!-- Wrong — manual nonce breaks auto-injection -->
<script nonce="{{ csp_nonce }}" src="/static/app.js"></script>
```

**Style tags** must use the `{{ csp_nonce }}` template variable:

```html
<style nonce="{{ csp_nonce }}">
    .highlight { color: red; }
</style>
```

CSP is fully enforced in both production and debug mode by default, so
"works locally, breaks in prod" violations are caught at write time rather
than at deploy time. Set `CSP_ENFORCE_CSP_IN_DEBUG=false` to opt into the
legacy soft mode where debug emits `Content-Security-Policy-Report-Only`
instead. Configure extra sources via `CSP_EXTRA_SCRIPT_SRC`,
`CSP_EXTRA_STYLE_SRC`, `CSP_EXTRA_IMG_SRC`, `CSP_EXTRA_CONNECT_SRC`,
`CSP_EXTRA_FONT_SRC`, `CSP_EXTRA_MEDIA_SRC` environment variables.

The middleware always sets `X-Content-Type-Options: nosniff`. If a
response has no `Content-Type` header (e.g. a bare
`Response(status_code=404)` with no `media_type=`), the middleware fills
in `text/plain; charset=utf-8`. Without this guard, nosniff combined
with a missing `Content-Type` makes Safari/Firefox save the response as
a 0-byte download and Chrome show a generic error page.

**Strict `style-src` (opt-in, requires `vibetuner` ≥ 10.11.0):** Set
`CSP_STYLE_SRC_STRICT=true` to drop `'unsafe-inline'` from `style-src`
and use the request nonce instead. Inline `style="..."` attributes will
be blocked by the browser and every `<style>` tag must carry
`nonce="{{ csp_nonce }}"`. Framework templates already follow this
pattern; htmx 4.0.0-beta4's indicator stylesheet uses a constructable
`CSSStyleSheet` so no inline style is needed there either. Audit user
templates for inline `style="..."` before flipping. On older releases
the env var is silently ignored, so bump `vibetuner` in `pyproject.toml`
and re-run `uv sync` first.

**htmx CSP Protection (default-on, requires `htmx.org@4.0.0-beta4`):**
htmx 4.0.0-beta4 ships an `hx-csp` extension (renamed from `hx-nonce`
in beta3) that strips htmx attributes from elements without a matching
`hx-nonce`. It is loaded by default from the framework-managed block of
`config.js` (`import "@alltuner/vibetuner/htmx/csp";`, re-exported from
the framework's pinned htmx, so no direct `htmx.org` dep is needed;
added in 10.20.0). It is not optional: it is what makes `hx-on:` /
`hx-live` work at all under vibetuner's strict CSP. The extension is
fail-closed — every element carrying an `hx-*` attribute needs a matching
`hx-nonce` — but `SecurityHeadersMiddleware` auto-stamps `hx-nonce` on
every htmx element (the same way it injects the `nonce` into `<script>`
tags), so there is no `body_attrs` stamp and no per-element `hx-nonce`
to add. The `csp` import also flips `htmx.config.safeEval = true` before
the extension registers, so `hx-on` / `hx-vals js:` / `hx-confirm js:`
are evaluated via nonce-based `<script>` injection rather than
`new Function()`; no `safeEval` meta tag is required. The HTML attribute
is still named `hx-nonce`; only the extension itself was renamed. On
older releases that ship `htmx.org@4.0.0-beta3` the file is named
`hx-nonce.js`.

**htmx Live Reactivity (default-on, requires `@alltuner/vibetuner` ≥ 10.15.0):**
htmx 4's `hx-live` extension is loaded by default from the
framework-managed block of `config.js`, alongside `hx-preload`. This is
vibetuner's recommended path for client-side reactivity — chip lists,
derived form fields, live filters, paired controls, inline validation.
Reach for it before adding Alpine.js, Stimulus, or hand-rolled
event-listener boilerplate.

**Why it fits the stack.** Vibetuner's `script-src 'nonce-X' 'strict-dynamic'`
CSP (no `'unsafe-eval'`) blocks inline `onclick="..."` / `onchange="..."`
attributes at the spec level, and would also reject htmx's own `new Function()`
evaluation of `hx-on:` / `hx-live` expressions with an `EvalError`. The
default-on `hx-csp` extension fixes that: with `safeEval` on, it evaluates
those expressions via nonce-based `<script>` injection, which the nonce +
`strict-dynamic` CSP does permit. That is what makes `hx-on:` and `hx-live`
work where raw handler attributes do not — no `'unsafe-eval'` needed.

**Primitives** (full reference at <https://four.htmx.org/extensions/hx-live/>):

- `hx-live="<expr>"` — JS expression re-run on any `input`/`change`/mutation,
  with `q()`, `wait`, `trigger`, `debounce`, and the htmx public API in scope.
  Async function body (top-level `await` allowed).
- `q(selector)` — jQuery-like proxy. Selector grammar: `next` / `prev` /
  `closest`, `'.foo in #scope'`, `'.foo in this'`, chained `.q(...)`. Reads
  return the first match; assigns write to all matches. `q('.x').arr()`
  for a real `Array<Element>`.
- Built-in shortcuts: `.trigger(name, detail)`, `.insert(pos, html)` (raw
  `insertAdjacentHTML` — does not run `htmx.process()`), `.take(class, from)`
  (move class from peers).
- Sigil `toggle('@attr')` / `toggle('*display=none|block')` for attribute /
  style flips.
- `debounce(ms)` — per-element, cancels prior in-flight via async rejection.
- `htmx.live.*` — same primitives outside expression scope (e.g.
  `htmx.live.take(target, className, source)` for the migrated
  `htmx.takeClass()`).

**Pattern: chip-list with derived hidden input** (the OAuth scope editor in
`debug/oauth_app_form.html.jinja` is the canonical in-tree example):

```jinja
<div id="scopes-tags"
     hx-on:click="
       const btn = event.target.closest('button[data-action=remove-scope]');
       if (btn) btn.closest('.badge').remove();
     ">
  {% for scope in scopes %}
    <span class="badge" data-scope="{{ scope }}">
      <span data-text>{{ scope }}</span>
      <button type="button" data-action="remove-scope">×</button>
    </span>
  {% endfor %}
</div>
<input type="hidden" name="scopes"
       hx-live="this.value = q('#scopes-tags .badge').arr()
                             .map(b => b.dataset.scope).join(',')">
```

The hidden input recomputes on every mutation under `#scopes-tags` — add
and remove paths stay in sync without manual wiring. Event delegation on
the container handles both initially-rendered and dynamically-inserted
badges (`q().insert()` does not re-process inserted nodes).

**Pattern: debounced live search:**

```jinja
<output hx-live="
  let term = q('#q').value;
  if (!term) { this.textContent = ''; return; }
  await debounce(250);
  this.textContent = await fetch('/search?q=' +
    encodeURIComponent(term)).then(r => r.text());
"></output>
```

**Rough edges:**

- **The DOM is the only source of truth.** No JS-variable reactivity; share
  state via `data-*` attributes or hidden inputs.
- **Expressions re-run on every DOM mutation.** Idempotent or
  cheap-or-guarded only. The runtime deactivates expressions that mutate
  more than 50 times per second.
- **Set-property writes broadcast silently** to all matched elements.
  Narrow your selectors.
- **`next` / `prev` / `closest` anchor to `this`.** Undefined when called
  from `htmx.live.q(...)` outside an expression.
- **`q().insert()` is raw `insertAdjacentHTML`.** Dynamic `hx-on:` /
  `hx-live` attributes on inserted markup won't be wired. Use event
  delegation on a stable parent or call `htmx.process(elt)` after insertion.
- **Breaking from beta2:** `htmx.takeClass()` / `htmx.forEvent()` moved
  out of core. Use `htmx.live.take(...)` / `htmx.live.forEvent(...)`.
  Framework code has no usages, so this is a non-event for users on the
  default scaffolding; user code calling those globals will need an update.

### Background Tasks

Run long-running or scheduled work outside the request cycle using Vibetuner's
background task system, powered by Streaq and Redis.

**Note:** In all examples, `app` refers to your project's Python package (the directory
under `src/`). The actual name depends on your project slug.

#### Prerequisites

Background tasks require Redis. Set `REDIS_URL` in your `.env`:

```bash
REDIS_URL=redis://localhost:6379
```

When using Docker development (`just dev`), Redis is started automatically.

#### Quick Start

1. Create a task in `src/app/tasks/`:

```python
# src/app/tasks/emails.py
from vibetuner.tasks.worker import get_worker

worker = get_worker()

@worker.task()
async def send_welcome_email(user_id: str) -> dict[str, str]:
    from vibetuner.models import UserModel
    from vibetuner.services.email import EmailService

    user = await UserModel.get(user_id)
    if user:
        email_service = EmailService()
        await email_service.send_email(
            to_address=user.email,
            subject="Welcome!",
            html_body="<h1>Welcome!</h1>",
            text_body="Welcome!",
        )
        return {"status": "sent", "email": user.email}
    return {"status": "skipped"}
```

2. Register in `tune.py`:

```python
from vibetuner import VibetunerApp
from app.tasks.emails import send_welcome_email

app = VibetunerApp(tasks=[send_welcome_email])
```

3. Enqueue from a route:

```python
task = await send_welcome_email.enqueue(str(user.id))
```

4. Start the worker:

```bash
just worker-dev
# Or: uv run vibetuner run dev worker
```

#### Worker Context

Access the worker context (the object yielded by the worker lifespan) with
`worker.context` inside a running task:

```python
from vibetuner.tasks.worker import get_worker

worker = get_worker()

@worker.task()
async def fetch_external_data(url: str) -> dict:
    response = await worker.context.http_client.get(url)
    return {"status": response.status_code, "data": response.text[:100]}
```

#### The `@robust_task()` Decorator

For tasks needing automatic retries and dead letter tracking:

```python
from vibetuner.tasks.robust import robust_task

@robust_task(max_retries=5, backoff_max=600)
async def send_webhook(payload: dict) -> dict:
    import httpx
    async with httpx.AsyncClient() as client:
        resp = await client.post("https://example.com/hook", json=payload)
        resp.raise_for_status()
    return {"status": "delivered"}
```

Parameters: `max_retries` (default 3), `backoff_base` (default 2.0),
`backoff_max` (default 300.0), `timeout`, `on_failure` callback.

Failed tasks are stored in the `dead_letters` MongoDB collection.

#### The `@robust_cron()` Decorator

For scheduled tasks that need retries and dead letter tracking, use
`@robust_cron()` instead of `@worker.cron()`:

```python
from vibetuner.tasks.robust import robust_cron

@robust_cron("*/15 * * * *", max_retries=5, backoff_max=120)
async def refresh_caches():
    """Refresh external caches with retry on failure."""
    import httpx
    async with httpx.AsyncClient() as client:
        resp = await client.get("https://api.example.com/cache/refresh")
        resp.raise_for_status()
```

Parameters: `tab` (crontab expression, required), `max_retries` (default 3),
`backoff_base` (default 2.0), `backoff_max` (default 300.0), `timeout`,
`on_failure` callback, plus extra `**cron_kwargs` forwarded to `worker.cron()`.

Retry behavior, dead letter collection, and failure callbacks work identically
to `@robust_task()`.

#### Scheduled Tasks (Cron)

For simple scheduled tasks without retries, use `@worker.cron()`:

```python
@worker.cron("0 9 * * *")  # Every day at 9:00 AM UTC
async def daily_digest():
    ...

@worker.cron("*/15 * * * *")  # Every 15 minutes
async def check_expired_sessions():
    ...
```

Cron tasks only execute inside the worker process.

#### SSE Integration

Broadcast real-time updates from background tasks to connected clients:

```python
from vibetuner.sse import broadcast

@worker.task()
async def process_upload(file_id: str, user_id: str) -> dict:
    await broadcast(f"upload:{user_id}", "progress", data="Processing...")
    # ... do work ...
    await broadcast(f"upload:{user_id}", "complete", data="Done!")
    return {"status": "complete"}
```

Broadcasting from tasks requires Redis for pub/sub across processes.

#### Custom Worker Lifespan

```python
from contextlib import asynccontextmanager
from vibetuner.context import Context
from vibetuner.tasks.lifespan import base_lifespan

@asynccontextmanager
async def worker_lifespan():
    async with base_lifespan() as context:
        print("Worker starting with custom setup")
        yield context
        print("Worker shutting down")
```

#### Running Workers

```bash
# Development
just worker-dev
just local-all-with-worker

# Production
docker compose -f compose.prod.yml up
vibetuner run prod worker --workers 4
```

Configuration: `REDIS_URL` (required), `WORKER_CONCURRENCY` (default 16),
`--port` flag (default 11111 for monitoring UI).

Connection resilience: the worker holds a long-lived Redis connection. Without
a socket timeout, a silently-dropped TCP connection (a VPN/network blip) leaves
a blocking read that never returns, wedging the worker's event loop
indefinitely. `REDIS_SOCKET_TIMEOUT` (default 30s, 0 disables),
`REDIS_SOCKET_CONNECT_TIMEOUT` (default 10s), `REDIS_SOCKET_KEEPALIVE` (default
true), and `REDIS_HEALTH_CHECK_INTERVAL` (default 30s) make a dead connection
raise instead of hang, so the worker reconnects or exits and is restarted.

Liveness watchdog: as a backstop for any event-loop stall (not just Redis), the
worker runs a daemon thread that force-exits the process if the loop stops
ticking for `WORKER_WATCHDOG_TIMEOUT` seconds (default 60, 0 disables;
`WORKER_WATCHDOG_INTERVAL` default 5), so its `restart` policy starts a fresh
worker.

Worker healthcheck: `vibetuner worker-health` exits non-zero when no live
worker is found (it checks for a fresh streaq health key in Redis, renewed from
inside the worker's event loop). The scaffolded `compose.prod.yml` wires it as
the worker service healthcheck for orchestrators / autoheal; recovery on plain
Compose comes from the watchdog.

#### Testing Tasks

Use the `mock_tasks` fixture:

```python
async def test_signup_queues_email(vibetuner_client, mock_tasks):
    with patch("app.tasks.emails.send_welcome_email", mock_tasks.send_welcome_email):
        resp = await vibetuner_client.post("/signup", data={"email": "a@b.com"})
    assert mock_tasks.send_welcome_email.enqueue.called
```

### Runtime Configuration

A layered configuration system for managing application settings that can be changed
at runtime and optionally persisted to MongoDB.

#### Overview

Runtime configuration provides settings that:

- Can be changed without redeploying the application
- Persist across server restarts (when MongoDB is available)
- Support in-memory overrides for debugging and testing
- Integrate with a debug UI at `/debug/config`

This is separate from `CoreConfiguration` (`.env` settings) which handles
framework-level settings loaded at startup.

#### Register Configuration Values

Register config values at module load time, typically in `src/app/config.py`:

```python
from vibetuner.runtime_config import register_config_value

register_config_value(
    key="features.dark_mode",
    default=False,
    value_type="bool",
    category="features",
    description="Enable dark mode for users",
)

register_config_value(
    key="limits.max_uploads",
    default=10,
    value_type="int",
    category="limits",
    description="Maximum uploads per user per day",
)
```

Secret values (`is_secret=True`) are masked in the debug UI and cannot be edited.

#### Access Configuration Values

```python
from vibetuner.runtime_config import get_config

async def some_handler():
    dark_mode = await get_config("features.dark_mode")
    max_items = await get_config("unknown.key", default=50)
```

#### Layered Resolution

Values are resolved with this priority (highest to lowest):

1. **Runtime overrides** — In-memory overrides set programmatically or via debug UI
2. **MongoDB values** — Persisted values that survive restarts
3. **Environment variables** — Derived from the key by uppercasing and replacing
   dots with underscores (e.g. `services.anthropic_api_key` →
   `SERVICES_ANTHROPIC_API_KEY`). Read from `os.environ` first, then from the
   merged `.env` / `.env.local` files. Coerced to the registered `value_type`;
   bogus values log a warning and fall through. Requires a worker/frontend
   restart to pick up changes.
4. **Registered defaults** — Default values defined in code

For `is_secret=True` keys, `/debug/config/<key>` renders a "Set this value"
card showing the env-var name, the matching `vibetuner config set <key>` CLI
command, and the `.env` entry to write, plus a worker/frontend restart
reminder. This unblocks first-time admins who would otherwise hit a dead-end
"this configuration is marked as secret" alert.

#### Value Types

Supported types: `bool`, `int`, `float`, `str`, `json`. Values are automatically
validated and converted when set.

#### `@config_value` Decorator

```python
from vibetuner.runtime_config import config_value

@config_value("features.dark_mode", value_type="bool", category="features")
def dark_mode() -> bool:
    """Enable dark mode for users."""
    return False

enabled = await dark_mode()
```

#### `ConfigGroup` Class

Group related config values into a typed class:

```python
from vibetuner.runtime_config import ConfigGroup, ConfigField

class FeatureFlags(ConfigGroup, category="features"):
    dark_mode = ConfigField(default=False, value_type="bool", description="Enable dark mode")
    max_items = ConfigField(default=50, value_type="int", description="Max items per page")

enabled = await FeatureFlags.dark_mode
limit = await FeatureFlags.max_items
```

Each field is registered under `"{category}.{field_name}"`.

#### When to Use Each API

| API | Best for |
|-----|----------|
| `register_config_value()` | Imperative registration at module level |
| `@config_value()` | Single standalone config values with defaults |
| `ConfigGroup` | Groups of related settings (feature flags, limits) |

#### `set_config()` Convenience Function

Persist a config value, inferring metadata from the registry:

```python
from vibetuner.runtime_config import set_config

await set_config("features.dark_mode", True)
```

The key must be registered. Raises `KeyError` if not. For unregistered keys,
use `RuntimeConfig.set_value()` with explicit metadata.

#### Registration via `VibetunerApp`

Register config values declaratively in `tune.py`:

```python
app = VibetunerApp(
    runtime_config={
        "features.dark_mode": {
            "default": False,
            "value_type": "bool",
            "description": "Enable dark mode",
            "category": "features",
        },
    },
)
```

#### CLI Management

```bash
vibetuner config list                              # View all values
vibetuner config set features.dark_mode -v true    # Set a value
vibetuner config set integrations.api_token        # Set secret (hidden prompt)
vibetuner config delete features.dark_mode --yes   # Delete, revert to default
```

#### MongoDB Persistence and Caching

When MongoDB is configured, values can be persisted and survive restarts. Config
values from MongoDB are cached for 60 seconds. Use `RuntimeConfig.refresh_cache()`
or the debug UI refresh button to force refresh.

### HTMX v2 to v4 Migration

Breaking changes when upgrading from htmx v2 to v4 in Vibetuner projects.

#### SSE: Native Support Replaces Extension

htmx v4 includes SSE in core. Remove `hx-ext="sse"`, rename `sse-connect` to
`hx-sse:connect`, and replace `sse-swap` — it is **removed** in v4 (no
equivalent). Named events are now dispatched as DOM events (consume with
`hx-trigger`); unnamed messages are swapped into the connecting element via its
own `hx-target`/`hx-swap`.

```html
<!-- Before (v2): sse-swap names the event to swap -->
<div hx-ext="sse" sse-connect="/events/notifications" sse-swap="update">

<!-- After (v4): hx-sse:connect opens the stream; a consumer re-fetches state -->
<div id="notifications-stream" hx-sse:connect="/events/notifications"></div>
<div hx-get="/notifications" hx-trigger="update from:#notifications-stream"></div>
```

#### Extension Auto-Registration

Extensions auto-register when imported — no `hx-ext` attribute needed.

#### `hx-vars` Replaced by `hx-vals` with `js:` Prefix

```html
<!-- Before: hx-vars="token:getToken()" -->
hx-vals='js:{"token": getToken()}'
```

#### `hx-disable` Renamed to `hx-ignore`

```html
<!-- Before: <div hx-disable> -->
<div hx-ignore>
```

#### Attribute Inheritance Requires `:inherited`

In v4, inheritance must be explicitly opted into:

```html
<!-- Before: <div hx-target="#results"> -->
<div hx-target:inherited="#results">
```

#### JavaScript Import Changes

```javascript
// Before (v2): import "htmx.org";
// After (v4):
import htmx from "@alltuner/vibetuner/htmx";
window.htmx = htmx;

// Preload extension:
// Before: import "htmx-ext-preload";
// After:
import "@alltuner/vibetuner/htmx/preload";

// SSE extension:
// Before: import "htmx-ext-sse";
// After:
import "@alltuner/vibetuner/htmx/sse";
```

`@alltuner/vibetuner` re-exports htmx as a subpath, so scaffolded projects don't need
`htmx.org` as a direct dependency. The bare-specifier import works under any package
manager linker mode (Bun hoisted or isolated, pnpm-style stores, npm v9+ isolated).

#### Migration Checklist

- Remove all `hx-ext="sse"` attributes from SSE elements
- Remove all other `hx-ext="..."` attributes (extensions auto-register)
- Replace `hx-vars` with `hx-vals` using `js:` prefix
- Replace `hx-disable` with `hx-ignore`
- Add `:inherited` modifier to attributes that rely on inheritance
- Update JS imports to use default import and `window.htmx = htmx`
- Update preload and SSE extension import paths
- Remove `htmx-ext-sse` and `htmx-ext-preload` from `package.json`

#### Beta3 Additions

htmx 4.0.0-beta3 (the 4.0 release candidate) ships several additions
relevant to vibetuner projects:

- **`hx-csp` extension** (introduced in beta3 as `hx-nonce`, renamed in
  beta4) — gates htmx attribute processing behind the page CSP nonce.
  Loaded by default from the framework-managed block of `config.js`
  (`import "@alltuner/vibetuner/htmx/csp"`; no direct `htmx.org` dep;
  added in 10.20.0); `SecurityHeadersMiddleware` auto-stamps the matching
  `hx-nonce` on every htmx element, so no manual stamping is needed.
  Elements without a matching nonce are stripped (fail-closed). The HTML
  attribute is still named `hx-nonce`; only the extension itself was renamed
- **`hx-live` extension** — DOM-reactivity via `hx-live="..."` plus a
  richer `hx-on` JS surface (`q()`, `toggle()`, `debounce()`). **Default-on
  in vibetuner** since `@alltuner/vibetuner` 10.15.0; see the Live
  Reactivity section above for patterns. Note: `htmx.takeClass` and
  `htmx.forEvent` moved out of core into this extension (now
  `htmx.live.take(...)` etc.)
- **`hx-history-elt` restored** — was removed in earlier 4.x pre-releases,
  brought back in beta3 alongside an improved `hx-history-cache`
  extension
- **`htmx:response:error` event** — fires for HTTP 4xx/5xx responses,
  restoring htmx 2's `htmx:responseError` convenience
- **`outerSync` swap style** — copies attributes onto target and replaces
  children, useful for clean `<body>` swaps in history replacement
- **`htmx.config.prefix` defaults to `"data-hx-"`** — both `hx-*` and
  `data-hx-*` work out of the box. Framework uses the canonical `hx-*`;
  no change needed
- **`hx-download` auto-detection** — extension now triggers a download
  when the response carries a `Content-Disposition` header, no per-element
  attribute required
- **`hx-preload` boost knobs** — added `boostEvent`, `boostTimeout`,
  `autoBoost` config keys for tighter `hx-boost` integration
- **Constructable indicator stylesheet** — htmx now uses a
  `CSSStyleSheet` instance for its indicator CSS, removing the last
  htmx-side reason to allow `'unsafe-inline'` on `style-src`. Pair with
  `CSP_STYLE_SRC_STRICT=true` to drop `'unsafe-inline'`
- **`hx-config` mode override removed** — security fix preventing a
  swap from downgrading origin enforcement
- **`hx-on::` shorthand fixed** — works in beta1+ (was broken in alpha8)

See [HTMX v2 to v4 Migration Guide](https://vibetuner.alltuner.com/htmx-migration/)
for the full list and the dedicated "Beta1 to Beta3 Changes" section.

### Import Ordering in tune.py

When configuring `tune.py`, import order matters. Vibetuner framework imports
(like `from vibetuner import VibetunerApp`) must come before your application
imports (like `from app.models import Post`). This ensures the framework is
initialized before your application code tries to use it.

```python
# src/app/tune.py — correct order
from vibetuner import VibetunerApp           # framework first

from app.models import Post, Comment          # then your app
from app.frontend.routes import app_router

app = VibetunerApp(
    models=[Post, Comment],          # Beanie (MongoDB) models
    sql_models=[SqlPost],            # SQLModel (SQL) models
    routes=[app_router],
)
```

## Reference

### CLI Reference

#### `vibetuner scaffold`

##### `new`

```bash
vibetuner scaffold new DESTINATION [options]
```

Creates a project from the local Vibetuner Copier template.

###### Options

- `--template`, `-t` – Use a different template source (local path, git URL, `github:user/repo`, etc.).
- `--defaults`, `-d` – Accept default answers for every prompt (non-interactive).
- `--data key=value` – Override individual template variables. Repeat for multiple overrides.
- `--branch`, `-b` – Use specific branch/tag from the vibetuner template repository.
- `DESTINATION` must not already exist.

###### Examples

```bash
# Interactive run
vibetuner scaffold new my-project
# Non-interactive defaults
vibetuner scaffold new my-project --defaults
# Override selected values in non-interactive mode
vibetuner scaffold new my-project \
    --defaults \
    --data project_name="My Project" \
    --data python_version="3.12"

# Test from a specific branch
vibetuner scaffold new my-project --branch fix/scaffold-command
```

##### `update`

```bash
vibetuner scaffold update [PATH] [options]
```

Brings an existing project up to date with the current template.

- `PATH` defaults to the current directory.
- `--skip-answered / --no-skip-answered` controls whether previously answered prompts are re-asked (defaults to skipping).
- `--branch`, `-b` – Use specific branch/tag from the vibetuner template repository.
- Exits with an error if `.copier-answers.yml` is missing.

##### `adopt`

```bash
vibetuner scaffold adopt [PATH] [options]
```

Adopts vibetuner scaffolding for an existing project that already has vibetuner as a dependency.

- `PATH` defaults to the current directory.
- Requires `pyproject.toml` with vibetuner in dependencies.
- Fails if `.copier-answers.yml` already exists (use `update` instead).

###### Options

- `--defaults`, `-d` – Accept default answers for every prompt (non-interactive).
- `--data key=value` – Override individual template variables.
- `--branch`, `-b` – Use specific branch/tag from the vibetuner template repository.

#### `vibetuner run`

Starts framework services without Docker.

##### `dev`

```bash
vibetuner run dev [frontend|worker] [--port PORT] [--host HOST] [--workers COUNT] [--auto-port]
```

- `--auto-port` – Use deterministic port based on project path (8001-8999). Mutually exclusive with `--port`.
- Sets `DEBUG=1` and enables hot reload.
- `service` defaults to `frontend`.
- Frontend watches `src/app/` and `templates/` for changes.
- Worker runs the Streaq worker with reload enabled (ignores `--workers` > 1).

##### `prod`

```bash
vibetuner run prod [frontend|worker] [--port PORT] [--host HOST] [--workers COUNT]
```

- Sets `ENVIRONMENT=production`.
- Disables hot reload and honors `--workers` for both frontend and worker services.
- Useful for containerless deployments or reproducing production settings locally.

#### `vibetuner db`

Database management commands for SQL databases (SQLModel/SQLAlchemy).

##### `create-schema`

```bash
vibetuner db create-schema
```

Creates all database tables defined in SQLModel metadata. This command:

1. Imports models from `app.models` to ensure they're registered
2. Creates tables in the database specified by `DATABASE_URL`
3. Skips if tables already exist (safe to run multiple times)

**Prerequisites:**

- `DATABASE_URL` environment variable must be set
- Models must be defined using SQLModel with `table=True`

**Note:** This command is only for SQL databases. MongoDB collections are created automatically when documents are inserted.

#### `vibetuner doctor`

Run diagnostic checks on your project:

```bash
vibetuner doctor
```

Validates project structure, configuration, service connectivity, models,
templates, dependencies, and port availability. Exits with code 1 if errors
are found.

#### `vibetuner config`

Manage runtime configuration values. Requires a project directory with MongoDB.

##### `list`

```bash
vibetuner config list
```

Displays all registered config keys with values, types, sources, and categories.
Secret values are masked.

##### `set`

```bash
vibetuner config set KEY [--value VALUE]
```

Sets a config value and persists to MongoDB. When `--value` is omitted for
secret keys, a hidden input prompt is used (avoids shell history exposure).
When omitted for non-secret keys, a regular prompt is used.

##### `delete`

```bash
vibetuner config delete KEY [--yes]
```

Deletes a config value from MongoDB, reverting to the registered default.
`--yes` skips the confirmation prompt.

#### `vibetuner debug`

Access debug dashboards on deployed applications.

##### `open`

```bash
vibetuner debug open URL [--secret SECRET]
```

Generates an HMAC-signed link (expires after 5 minutes) and opens it in the
default browser. Grants an 8-hour debug session cookie on the server.

- `URL` — Base URL of the deployed application (e.g., `https://myapp.com`)
- `--secret`, `-s` — Signing secret. Must match the server's `SESSION_KEY`.
  Reads from local `.env` when omitted.

```bash
# From a project directory
vibetuner debug open https://myapp.com

# From anywhere
uvx vibetuner debug open https://myapp.com --secret mysecretkey
```

#### `vibetuner crypto`

Manage encryption keys for fields encrypted with `EncryptedFieldsMixin`.

##### `set-key`

```bash
vibetuner crypto set-key [--key PASSPHRASE] [--env-file PATH]
```

Sets the encryption key and encrypts all existing plaintext secrets.
A secure random key is generated if `--key` is omitted. Errors if a key
is already configured (use `rotate-key` instead).

##### `rotate-key`

```bash
vibetuner crypto rotate-key [--new-key PASSPHRASE] [--env-file PATH]
```

Decrypts all secrets with the current key and re-encrypts with a new one.
Errors if no current key is configured (use `set-key` first).

#### `vibetuner version`

Show version information.

```bash
vibetuner version [--app]
```

##### Options

- `--app`, `-a` – Show app settings version even if not in a project directory.

### Scaffolding Reference

#### Template Prompts

- `company_name` – default `Acme Corp`. Displayed in generated metadata, email templates, and documentation.
- `author_name` – default `Developer`. Used for attribution in project metadata.
- `author_email` – default `dev@example.com`. Included in scaffolded docs and config.
- `project_name` – default `_folder_name`. Human-friendly name used throughout the README and docs.
- `project_slug` – default `_folder_name`. Must match `^[a-z][a-z0-9\-]*[a-z0-9]$` (used for Python package name,
  Docker image, compose project name).
- `project_description` – default `A project that does something useful.` Populates package metadata.
- `fqdn` – default empty. When set, enables production deployment extras (Caddy, Watchtower, etc.).
- `python_version` – default `3.14`. Controls `.python-version`, Docker images, and `uv` settings.
- `supported_languages` – default `[]`. JSON/YAML list of language codes (for example `["es", "fr"]`), adds
  translation skeletons.
- `redis_url` – default empty. Used when background jobs are enabled.
- `mongodb_url` – default empty. MongoDB connection string written to `.env.local`.
- `database_url` – default empty. SQL database connection string (PostgreSQL, MySQL, MariaDB, SQLite) written to `.env.local`.
- `docker_registry` – default `localhost:5050`. Only prompted when `fqdn` is set. Docker registry hostname for pushing
  and pulling production images.
- `use_self_hosted_runner` – default `false`. Only prompted when `fqdn` is set. Includes a GitHub Actions workflow for
  building and pushing Docker images on a self-hosted runner, triggered by releases.
- `enable_watchtower` – default `false`. Only prompted when `fqdn` is set; adds Watchtower service to production
  Docker Compose.

#### Updating Existing Projects

There are two supported update flows:

1. **`vibetuner scaffold update`** (works everywhere)

- Reads `.copier-answers.yml` and reapplies the latest template files.
- Respects previous answers by default; pass `--no-skip-answered` to revisit prompts.
- Runs the same post-generation tasks after updating files.

2. **`just update-scaffolding`** (inside generated projects)

- Shells out to `copier update -A --trust`, then re-syncs dependencies (`bun install`, `uv sync --all-extras`).
- Useful when you already have the project checked out with scaffolded `justfile`.

Both commands update tracked files. Always commit or stash local changes before running them, review the results, and
resolve any merge prompts Copier surfaces.

### Deployment

#### Docker Production Build

Vibetuner includes a multi-stage Dockerfile optimized for production.

##### Test Production Build Locally

```bash
just test-build-prod
```

This builds and runs the production image locally.

##### Build and Push

```bash
just release
```

This builds the production image and pushes to your container registry.

#### Environment Configuration

##### Production Environment Variables

Create a `.env` file for production:

```bash
# Application
APP_NAME=My Application
SECRET_KEY=your-production-secret-key
DEBUG=false
ENVIRONMENT=production
# Database (MongoDB)
MONGODB_URL=mongodb://user:password@mongodb-host:27017/myapp?authSource=admin
# Or SQL database (PostgreSQL, MySQL, MariaDB, SQLite)
DATABASE_URL=postgresql+asyncpg://user:password@postgres-host:5432/myapp
# Redis (if background jobs enabled)
REDIS_URL=redis://redis-host:6379/0
# Email
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=your-sendgrid-api-key
FROM_EMAIL=noreply@example.com
# OAuth
GOOGLE_CLIENT_ID=your-production-client-id
GOOGLE_CLIENT_SECRET=your-production-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-secret
# Session
SESSION_COOKIE_SECURE=true
SESSION_COOKIE_SAMESITE=lax
SESSION_MAX_AGE=2592000
# Storage (if using S3)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_S3_BUCKET=your-bucket
AWS_REGION=us-east-1
```

#### Deployment Options

##### Docker Compose

Use `compose.prod.yml` for production deployment:

```bash
docker compose -f compose.prod.yml up -d
```

This starts:

- Database with persistence (MongoDB or PostgreSQL)
- Redis (if enabled)
- Your application

##### Cloud Platforms

###### Railway

1. Connect GitHub repository
2. Add database plugin (MongoDB or PostgreSQL)
3. Configure environment variables
4. Deploy automatically on push

###### Render

1. Create new Web Service
2. Connect repository
3. Add environment variables
4. Render will auto-deploy

## Development

### Contributing Guidelines

#### About This Project

Vibetuner was born to meet the needs of [All Tuner Labs](https://alltuner.com) when spawning new projects. It embodies our core beliefs:

- **Simplicity**: Minimal boilerplate, clear conventions
- **Speed of Iteration**: Fast development cycles, hot reload, minimal friction
- **Modern Technology Stack**: Latest stable versions, async-first architecture
- **Good Integration with Coding Assistants**: Well-documented, predictable patterns

#### About Contributions

While we welcome feedback and are happy to see community interest, please note:

- **We may not accept all pull requests** - The project serves specific internal needs and design goals
- **Response times may vary** - This is one of many projects we maintain
- **Breaking changes may occur** - We prioritize our internal requirements
- **No guarantees on feature requests** - We'll consider them, but can't commit to implementing everything

That said, we do appreciate good contributions that align with our core beliefs (simplicity, speed, modern stack,
assistant-friendly) and will do our best to review them when time allows.

#### PR Title Format (Important!)

This project uses **Release Please** for automated changelog generation. Since we squash PRs, **PR title becomes the
commit message** that determines version bumps and changelog entries.

##### Required Format

```text
<type>[optional scope]: <description>
```

##### Supported Types and Version Impact

| Type | Description | Version Impact |
|------|-------------|----------------|
| `feat` | New features | **MINOR** |
| `fix` | Bug fixes | **PATCH** |
| `revert` | Reverts of previous changes | **PATCH** |
| `docs` | Documentation changes | **PATCH** |
| `chore` | Maintenance, dependencies | **PATCH** |
| `refactor` | Code refactoring | **PATCH** |
| `style` | Formatting, linting | **PATCH** |
| `test` | Test changes | **PATCH** |
| `perf` | Performance improvements | **MINOR** |
| `ci` | CI/CD changes | **PATCH** |
| `build` | Build system changes | **PATCH** |

When reverting a change, the PR title must start with `revert:` (not the default
`Revert "..."` subject `git revert` produces). Otherwise Release Please silently
drops the entry and the changelog still shows the reverted feature as added.

##### Breaking Changes

Add `!` to indicate breaking changes (triggers **MAJOR** version):

- `feat!: remove deprecated API`
- `fix!: change database schema`

##### Examples

###### Good PR Titles

```text
feat: add OAuth authentication support
fix: resolve Docker build failure
docs: update installation guide
chore: bump FastAPI dependency
feat(auth): add Google OAuth provider
feat!: remove deprecated authentication system
```

###### Bad PR Titles (Release Please can't categorize)

```text
Add OAuth
Fix Docker
Update docs
Authentication changes
OAuth implementation
```

## Packages

### Python Package

**Location**: `vibetuner-py/`
Published to PyPI, provides:

- Core framework code
- Authentication system
- Database integration (MongoDB and SQL)
- Email and storage services
- CLI commands
- Blessed dependency stack

**Install**: `uv add vibetuner`

**Dependencies**:

- FastAPI with async support
- MongoDB with Beanie ODM
- SQLModel with SQLAlchemy
- Granian ASGI server
- Authlib for OAuth
- HTMX integration
- Background job support (Redis/Streaq)
- Email services
- CLI tools

### JavaScript Package

**Location**: `vibetuner-js/`
Published to npm, provides:

- Frontend build dependencies (Tailwind, esbuild, etc.)
- Version-locked with Python package
- No runtime dependencies

**Install**: `bun add @alltuner/vibetuner`

**Dependencies**:

- Tailwind CSS v4
- DaisyUI components
- HTMX and extensions
- Build tools

### Repository

**Source Code**: [github.com/alltuner/vibetuner](https://github.com/alltuner/vibetuner)

Contains:

- Scaffolding template (`vibetuner-template/`)
- Python package source (`vibetuner-py/`)
- JavaScript package source (`vibetuner-js/`)
- Documentation (`vibetuner-docs/`)
- CI/CD workflows (`.github/workflows/`)

**Issue Tracking**: Use GitHub Issues for bug reports and feature requests.

## Optional

### Development Setup

#### Setting Up the Development Environment

```bash
# Clone repository
git clone https://github.com/alltuner/vibetuner
cd vibetuner

# Set up Python package
cd vibetuner-py
uv sync

# Set up JavaScript package
cd ../vibetuner-js
bun install

# Test scaffold command
uv run --directory ../vibetuner-py vibetuner scaffold new /tmp/test-project
```

#### Code Style

- **Python**: Follow existing style, use Ruff for formatting
- **JavaScript**: Follow existing style
- **Commits**: Clear, concise messages describing "why"

#### Testing

Before submitting:

```bash
# Format Python code
cd vibetuner-py
ruff format .

# Check for issues
ruff check .

# Test scaffold command
uv run vibetuner scaffold new /tmp/test-project --defaults
cd /tmp/test-project
just dev  # Should start without errors
```

### Internal Documentation

The `vibetuner-docs/docs/` directory contains the source files for all documentation. These are built using MkDocs and
deployed to GitHub Pages.

**Documentation Structure**:

- `index.md` - Main landing page
- `quick-start.md` - Getting started guide
- `development-guide.md` - Daily development workflow
- `architecture.md` - System design and structure
- `tech-stack.md` - Technology choices and rationale
- `authentication.md` - Authentication setup and configuration
- `deployment.md` - Production deployment guide
- `cli-reference.md` - Command-line reference
- `scaffolding.md` - Template customization
- `contributing.md` - Contribution guidelines
- `development.md` - Development setup for contributors
- `changelog.md` - Version history

**Building Documentation**:

```bash
just docs-serve  # Local development with live reload
just docs-build  # Production build
```

The documentation is automatically built and deployed to `https://vibetuner.alltuner.com/` on releases.