DIRECTIVE FOR AI AGENTS
MANDATORY: All internal module imports must use the @/ path alias. Check tsconfig.json before creating new paths. Primitives MUST reside in @/components/ui/.

Import Standards

The Verbiage

The Rule

All imports must use the @/ alias. No relative paths (../../) are allowed for internal modules. The @/ alias is defined in tsconfig.json and maps to ./src/*, providing a consistent, maintainable import structure across the entire codebase.

Relative paths create maintenance nightmares. When files move, relative imports break. The @/ alias ensures imports remain valid regardless of file location, making refactoring safe and predictable.

Shadcn Registry

Primitives: UI primitives from the Shadcn registry live in @/components/ui/. These are reusable, headless components like Button, Dialog, Popover, and Command. They follow the Shadcn design system and are imported directly from their UI directory.

Business Components: Feature-specific components live in @/components/[feature]/. For example, @/components/library-sidebar-nav or @/components/volume-switcher. These components may use UI primitives but are specific to application features.

Config Files: Configuration and data live in @/config/. Examples include @/config/library-mapping and @/config/docs.

Utilities: Shared utilities and helpers live in @/lib/. Examples include @/lib/utils for the cn function and @/lib/sidebar-config for sidebar configuration logic.

The Blueprint

typescript
// ============================================
// ❌ BAD: Relative imports break when files move
// ============================================
import { Button } from '../../ui/button';
import { Header } from '../header';
import { libraryVolumes } from '../../../config/library-mapping';
import { cn } from '../../lib/utils';

// Problems:
// - Breaks when files are moved or reorganized
// - Hard to count ../ levels
// - Inconsistent across the codebase
// - Makes refactoring dangerous

// ============================================
// ✅ GOOD: @/ alias works from any file location
// ============================================
import { Button } from '@/components/ui/button';
import { Header } from '@/components/header';
import { libraryVolumes } from '@/config/library-mapping';
import { cn } from '@/lib/utils';

// Benefits:
// - Always works regardless of file location
// - Consistent across entire codebase
// - Safe to refactor
// - Clear and readable

// ============================================
// ✅ GOOD: Shadcn primitives from UI directory
// ============================================
import { Button } from '@/components/ui/button';
import { Dialog, DialogContent } from '@/components/ui/dialog';
import { Popover, PopoverTrigger } from '@/components/ui/popover';

// ============================================
// ✅ GOOD: Business components from components directory
// ============================================
import { LibrarySidebarNav } from '@/components/library-sidebar-nav';
import { VolumeSwitcher } from '@/components/volume-switcher';
import { BiblePageLayout } from '@/components/bible-page-layout';

// ============================================
// ✅ GOOD: Config and utilities
// ============================================
import { libraryVolumes } from '@/config/library-mapping';
import { getSidebarConfig } from '@/lib/sidebar-config';
import { cn } from '@/lib/utils';

The AI Context

text
Always use the @/ path alias for internal imports. The alias is configured in tsconfig.json as "@/*": ["./src/*"]. This means @/components maps to ./src/components, @/config maps to ./src/config, and @/lib maps to ./src/lib. Never use relative paths like ../../ or ../. The @/ alias ensures imports remain valid when files are moved or reorganized.

Directive for AI Agents

Copy and paste this directive to instruct an AI assistant on how to maintain this specific pattern:

text
## Directive for AI Agents

Before saving any file, perform a linting check on imports. If a relative path is found, refactor it to use the @/ alias immediately.

**Required Pattern:**
- ✅ `import { Component } from '@/components/component'`
- ✅ `import { Primitive } from '@/components/ui/primitive'`
- ✅ `import { Config } from '@/config/config'`
- ✅ `import { util } from '@/lib/util'`

**Forbidden Patterns:**
- ❌ `import { Component } from '../../components/component'`
- ❌ `import { Component } from '../component'`
- ❌ `import { Component } from './component'` (for internal modules)
- ❌ Any relative path for files within the src/ directory

**Refactoring Rule:**
When you encounter a relative import, convert it immediately:
1. Count the `../` levels to determine the target directory
2. Replace with `@/` + the path from src/
3. Verify the import resolves correctly
4. Save the file only after all imports use @/ alias

The @/ alias is the single source of truth for internal module resolution.