addmon/AGENTS.md

# Agent Guidelines for addmon

## Development Commands

### Essential Commands

- `bun run dev` - Start all applications in development mode
- `bun run dev:web` - Start only the web application on port 3001
- `bun run build` - Build all applications
- `bun run check` - Run Oxlint and Oxfmt formatting
- `bun run check-types` - TypeScript type checking across all apps

### Web-Specific Commands (in apps/web)

- `bun run check-types` - TypeScript type checking for web app only
- `bun run desktop:dev` - Start Tauri desktop app in development
- `bun run desktop:build` - Build Tauri desktop app

### Testing

**No test framework configured** - This project does not currently have tests. When adding tests, consider Vitest (already configured in oxlint settings).

## Code Style Guidelines

### Linting and Formatting

- **Tool**: Oxlint (linting) + Oxfmt (formatting)
- **Configuration**: Root `.oxlintrc.json`
- **Run**: `bun run check` (lints and auto-formats)
- **All rules set to "warn" level** - Never use `as any`, `@ts-ignore`, or `@ts-expect-error`

### TypeScript Configuration

- **Strict mode enabled** with additional checks:
  - `noUncheckedIndexedAccess` - Require checks for potentially undefined array/object access
  - `noUnusedLocals` / `noUnusedParameters` - Remove unused variables
  - `noFallthroughCasesInSwitch` - Explicit break/return in all switch cases
- **Target**: ESNext with bundler module resolution
- **Path alias**: `@/*` → `./src/*`

### Import Order and Grouping

```tsx
// 1. External libraries (React, TanStack, etc.)
import { createFileRoute } from "@tanstack/react-router";
import { cva } from "class-variance-authority";

// 2. Internal imports with @/ alias
import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";
import Header from "@/components/header";

// 3. Type imports (use `import type` for type-only imports)
import type { VariantProps } from "class-variance-authority";
```

### Component Patterns

- **Props**: Use TypeScript interfaces, prefer `VariantProps` for component variants
- **Destructuring**: Always destructure props with defaults
- **Variants**: Use `class-variance-authority` (cva) for styling variants
- **Classes**: Use `cn()` utility for class merging (from `@/lib/utils`)
- **Exports**:
  - UI components: Named exports for related components (e.g., `export { Button, buttonVariants }`)
  - Page components: Default exports for file-based routes
- **Data attributes**: Use `data-slot` for component composition patterns

Example component structure:

```tsx
function MyComponent({
  className,
  variant = "default",
  ...props
}: MyComponentProps & VariantProps<typeof myVariants>) {
  return <div className={cn(myVariants({ variant }), className)} {...props} />;
}

export { MyComponent };
```

### Styling Guidelines

- **Framework**: TailwindCSS v4 with OKLCH color space
- **Theme**: Dark mode by default, uses `next-themes` provider
- **CSS Variables**: Use semantic color tokens (e.g., `bg-background`, `text-foreground`)
- **Radius**: Base radius is `0.625rem`, use semantic tokens (`rounded-none` from shadcn pattern)
- **Custom variant**: Dark mode uses `@custom-variant dark (&:is(.dark *))`

### Routing Patterns (TanStack Router)

- **File-based routing**: Routes in `src/routes/`
- **Route definition**:
  ```tsx
  export const Route = createFileRoute("/")({
    component: HomePage,
  });
  ```
- **Root route**: Use `createRootRouteWithContext` for global context
- **Router setup**: `defaultPreload: "intent"` with pending component as `<Loader />`

### File Organization

```
src/
├── components/
│   ├── ui/         # shadcn/ui primitives
│   └── *.tsx       # Application-specific components
├── routes/         # TanStack Router files
├── lib/            # Utility functions (e.g., `cn()`)
└── main.tsx        # Entry point
```

### Naming Conventions

- **Components**: PascalCase (`Button.tsx`, `UserProfile.tsx`)
- **Utilities**: camelCase (`cn()`, `formatDate()`)
- **Constants**: UPPER_SNAKE_CASE (`TITLE_TEXT`, `API_URL`)
- **Files**: kebab-case for utilities, PascalCase for components

### Error Handling

- **Runtime errors**: Minimal current handling. Use try/catch for async operations
- **Type errors**: Fix directly, never suppress with type assertions
- **Validation**: Use Zod for schema validation (already in dependencies)

### Tauri Integration

- **Rust code**: Located in `src-tauri/src/`
- **Frontend-Rust bridge**: Use Tauri invoke patterns
- **Commands**: Build with `bun run desktop:build`, dev with `bun run desktop:dev`

## Project Context

- **Monorepo**: Turborepo with workspaces (apps/_, packages/_)
- **Package Manager**: Bun (1.3.5)
- **UI Framework**: React 19.2.3 with TanStack Router
- **Component Library**: shadcn/ui (base-lyra style, lucide icons)
- **Desktop**: Tauri v2 for cross-platform desktop apps

## Before Submitting Changes

1. Run `bun run check` to lint and format code
2. Run `bun run check-types` to verify type safety
3. Test dev server: `bun run dev:web`
4. No test coverage required yet (not configured)