ermnvldmr.com/GEMINI.md

AGENTS.md

Guidance and operational constraints for AI coding agents working on ermnvldmr.com.

1. System Overview & Tech Stack

ermnvldmr.com is a pnpm monorepo hosting personal web services, dividing applications into services/ and shared packages into packages/. The primary website (services/www) and static pages (services/static) are built with React 19 and Rsbuild (Rspack). Build-time Static Site Generation is performed via @ermnvldmr/ssg, a custom Rsbuild plugin that pre-renders React entry points to HTML with inlined critical CSS (via Critters). The documentation service (services/docs) runs on Hugo with the Hextra theme.

Shared workspace packages provide the UI design system (@ermnvldmr/ui), application component kits (@ermnvldmr/kits), standard types library (@ermnvldmr/stl), localization utilities (@ermnvldmr/i18n), monorepo CLI tooling (@ermnvldmr/cli), static site generator (@ermnvldmr/ssg), and reusable presets for ESLint, Rsbuild, and Storybook. Design components utilize Tailwind CSS v4, Radix UI primitives, React-Aria, and CVA, validated using Vitest and Storybook 8.

Technology	Version / Tool	Purpose
Package Manager	pnpm (>=9.12.3)	Workspace dependency and package management
Runtime Engine	Node.js (>=20)	Server and build runtime environment
UI Library	React 19 (react, react-dom)	Declarative UI rendering
Bundler Engine	Rsbuild / Rspack	Rust-powered bundling, hot module reloading, and build pipeline
Static Site Generator	@ermnvldmr/ssg / Hugo (>=0.110.0)	Build-time React HTML pre-rendering & Hugo docs engine
UI Primitives & Icons	React Aria, Radix UI, Lucide React	Accessible interactive primitives and icon system
Styling & Utilities	Tailwind CSS v4, CVA, @ermnvldmr/stl	Utility styling, component variant management, class utilities
Internationalization	@ermnvldmr/i18n	Multi-locale routing and localization strings (en, ru)
Testing Framework	Vitest, Testing Library, Playwright	Unit, integration, and Storybook interaction testing
Component Workshop	Storybook 8	Isolated component development environment
Static Analysis	ESLint 9 (Flat Config), TypeScript 5.8	Code linting, monorepo import boundary checks, strict typing
Secrets Encryption	@dotenvx/dotenvx	Public-key encrypted .env.dev secrets management

2. Project Structure & Key Directories

ermnvldmr.com/
├── ci/                      # CI/CD pipelines, Docker containers, deployment scripts
├── docs/                    # Architectural documentation and design specifications
├── packages/                # Monorepo shared packages and toolchain configurations
│   ├── cli/                 # Monorepo CLI utility (`ermnvldmr-cli`) for tasks like S3 asset sync
│   ├── eslint-config/       # Shared flat ESLint rule sets and monorepo import restriction rules
│   ├── i18n/                # Localization engine, locale pathing, and translation keysets
│   ├── kits/                # High-level domain & layout component kits (BentoGrid, InfoCard, PageHead, Page, etc.)
│   ├── rsbuild-config/      # Shared Rsbuild and Rspack bundler configuration presets
│   ├── ssg/                 # Build-time Static Site Generation plugin for Rsbuild React apps
│   ├── stl/                 # Standard Types Library for core utilities, type definitions, and react helpers
│   ├── storybook-config/    # Shared Storybook workshop configurations
│   └── ui/                  # Design system React component library, styles, and Storybook stories
├── services/                # Deployable web applications and services
│   ├── docs/                # Technical documentation site (Hugo + Hextra theme)
│   ├── static/              # Static landing pages service (Rsbuild + React 19)
│   └── www/                 # Primary website (Rsbuild + React 19 + MDX + SSG)
├── .env.dev                 # Encrypted environment variable storage (tracked in git)
├── .env.keys                # Private decryption keys (UNTRACKED - do not commit)
├── eslint.config.mjs        # Root ESLint flat configuration extending `@ermnvldmr/eslint-config`
├── pnpm-workspace.yaml      # Monorepo workspace package definitions
└── tsconfig.json            # Root TypeScript configuration with workspace path aliases

3. Setup & Commands

CLI Commands

• Install dependencies: pnpm install
• Development servers:
  • Website (services/www): pnpm www:dev (or pnpm dev:www)
  • Documentation (services/docs): pnpm docs:dev (or pnpm dev:docs)
  • UI Component Storybook (packages/ui): pnpm ui:storybook
  • Static landings (services/static): pnpm static:dev (or pnpm dev:static)
  • UI package build watcher: pnpm ui:dev
• Build:
  • Full workspace build: pnpm build
  • Workspace package dependencies only: pnpm build:deps
  • Individual package build: pnpm --filter @ermnvldmr/ui build
• Linting & Formatting:
  • Lint workspace: pnpm lint
  • Typecheck workspace: pnpm typecheck
  • Format files: pnpm format
• Testing:
  • Run full test suite: pnpm test
  • Test single package: pnpm --filter @ermnvldmr/ui test
  • Test single file: pnpm --filter @ermnvldmr/ui exec vitest run src/components/Button/Button.test.tsx
  • Test coverage: pnpm test:coverage

Environment Setup

• Environment variables are managed using @dotenvx/dotenvx.
• .env.dev contains encrypted values and is tracked in git.
• .env.keys contains local decryption keys (DOTENV_PRIVATE_KEY) and must never be committed.
• Environment variables:
  • LOCALE: Target build language (en or ru, defaults to en).
  • RSDOCTOR: Set RSDOCTOR=true during build to trigger Rsbuild bundle analysis.
  • S3 static sync credentials: COM_ERMNVLDMR_STATIC_S3_BUCKET, COM_ERMNVLDMR_STATIC_S3_REGION, COM_ERMNVLDMR_STATIC_S3_ENDPOINT_URL, COM_ERMNVLDMR_STATIC_AWS_ACCESS_KEY_ID, COM_ERMNVLDMR_STATIC_AWS_SECRET_ACCESS_KEY.

4. Non-Negotiable Coding Rules & Patterns

Typing & Documentation Rules

• Strict TypeScript: strict: true is enforced globally.
• Forbidden Types: any is strictly prohibited (@typescript-eslint/no-explicit-any: error).
• Forbidden Assertions: Type assertions (as Type) are strictly prohibited (@typescript-eslint/consistent-type-assertions: ['error', { assertionStyle: 'never' }]). Use explicit type guards or type casting helpers (e.g., castRef from @ermnvldmr/stl).
• Forbidden Non-Null Assertion: Non-null assertion operator (!) is prohibited (@typescript-eslint/no-non-null-assertion: error).
• Explicit Type Imports: Imports used strictly for types MUST use import type (@typescript-eslint/consistent-type-imports: error).
• Interface Definitions: Object shapes MUST use interface, not type aliases (@typescript-eslint/consistent-type-definitions: ['error', 'interface']).
• TSDoc Requirements: JSDoc comments are required on all exported function declarations, interfaces, and type declarations (jsdoc/require-jsdoc: error). A description string is mandatory (jsdoc/require-description: error).

Component Architecture & Structure

• Component implementations in packages/ui MUST live in dedicated PascalCase subdirectories: packages/ui/src/components/<ComponentName>/
  • <ComponentName>.tsx — Component logic and JSX
  • <ComponentName>.stories.tsx — Storybook stories
  • <ComponentName>.test.tsx — Vitest unit tests
• Styling: Component variant logic must use cva (class-variance-authority). Utility class merging must use cn(...) from @ermnvldmr/stl.
• Accessibility: Interactive elements must leverage react-aria hooks (useButton, useFocusRing, useHover) to maintain accessibility standards.
• Naming Conventions:
  • PascalCase for React component files and directories (Button/Button.tsx).
  • camelCase for helper modules, hooks, and utilities (path.ts, useTheme.ts).
  • kebab-case for configuration files (eslint.config.mjs, postcss.config.mjs).

State Management & Import Rules

• State Primitives: Use standard React state (useState, useReducer, useContext) and react-stately / react-aria primitives. Do not introduce unapproved third-party state managers.
• Monorepo Relative Imports: Code inside a package or service MUST use relative paths when referencing files within that same package. Importing the package's own published name inside itself (e.g. import ... from '@ermnvldmr/ui' inside packages/ui) is strictly prohibited and fails ESLint checks.

Anti-Patterns ("What NOT to do")

• DO NOT use any, as Type assertions, or ! non-null assertions.
• DO NOT introduce Vite, Webpack, or Next.js configurations. Rsbuild (Rspack) is the monorepo's standardized React bundler.
• DO NOT use self-referential package imports within workspace packages; use relative paths.
• DO NOT suppress linter or compiler errors with @ts-ignore, @ts-nocheck, or inline eslint disables without explicit user approval.
• DO NOT commit unencrypted .env files or secret keys (.env.keys).
• DO NOT run destructive Git operations (such as force pushing to main/next or dropping uncommitted user work) without authorization.

5. Critical Workflows & Safety Directives

Verification Workflow

Before completing any task, run and pass every step in the following sequence:

1. pnpm typecheck — 0 TypeScript compiler errors.
2. pnpm lint — 0 ESLint warnings (--max-warnings 0).
3. pnpm test — All unit and component tests passing.
4. pnpm build — Clean workspace compilation.

Protected Boundaries

The agent MUST NOT modify the following files or directories unless explicitly requested by the user:

• .env.keys (untracked decryption keys).
• pnpm-lock.yaml (dependencies must be managed exclusively through pnpm CLI commands).
• LICENSE file.
• services/docs/content/ and services/www/content/ creative and literary works.