# Agent Guidelines for dashboard/

These rules apply to the entire dashboard repository.
They exist to keep architecture stable when humans or AI agents modify code.

This repo contains:

- A large Next.js App Router application (dashboard)
- Vendored internal libraries under packages/\*
- No monorepo tooling assumptions beyond local file dependencies

AI agents MUST respect these boundaries.

---

## 1. Build, Lint & Test Commands

### Development

```bash
yarn dev              # Start development server with MCP server
yarn build            # Production build (runs prebuild scripts)
yarn build:static     # Static build (includes prebuild)
yarn start            # Start production server
yarn preview          # Build and start production server
```

### Code Quality

```bash
yarn lint             # Run ESLint (currently fails under Next 16 CLI; use eslint command below)
./node_modules/.bin/eslint . --no-eslintrc --config .eslintrc.json --resolve-plugins-relative-to .  # Run ESLint directly (ignore parent configs)
yarn typecheck        # TypeScript type checking
yarn format           # Format code with Prettier
```

### Testing

```bash
yarn test             # Run unit tests (Vitest)
yarn test:unit        # Run unit tests explicitly
yarn test:e2e         # Run E2E tests (Playwright)

# Run a single unit test file
yarn test path/to/file.test.ts
yarn test --run path/to/file.test.ts

# Run a single Playwright spec
yarn test:e2e path/to/spec.test.ts
```

---

## 2. Release Traceability Default Rule

For any change touching CI/CD, image tags, deploy contracts, `/api/ping`, or `validate` behavior:

- Treat `skills/release-traceability/SKILL.md` as the default reference before implementation.
- Prefer release metadata that can be traced from `build` to `deploy` to `validate` without manual injection.
- Keep the published image reference, runtime version, and validation output aligned.
- Do not introduce a deploy path that rebuilds images on the target host.

When in doubt, follow the skill first and keep the release chain fully auditable end to end.

---

## 3. Repository Mental Model (Read This First)

This repository has **three clearly separated layers**:

### A. Application Layer (Next.js App Router)

src/app/**, src/components/**, src/lib/**, src/state/**, src/modules/\*\*

This is the **only place** where:

- Routing exists
- Global state exists
- Runtime config is loaded
- Zustand is allowed

### B. Vendored Library Layer

packages/neurapress/\*\*

This is a **library**, not an application. It may contain:

- React components
- Editor logic
- Markdown utilities
- Styles and assets

It MUST NOT:

- Behave like a Next.js app
- Depend on dashboard routing or aliases
- Own global state

### C. Build / Runtime Glue

scripts/**, config/**, public/\*\*

Used for build-time or runtime wiring only.

---

## 4. Import & Alias Rules (Critical)

### Dashboard code (src/\*\*)

- Allowed: `import { X } from "@/components/X"`
- Group imports: React → third-party → local types → local components

```ts
import React, { useEffect } from "react";
import { Button } from "@radix-ui/react-button";
import type { User } from "@/types/user";
import { UserCard } from "@/components/UserCard";
```

### Vendored packages (packages/\*\*)

- 🚫 ABSOLUTELY FORBIDDEN: `@/` aliases inside packages
- ✅ Use relative imports or package exports

---

## 5. TypeScript & Formatting Rules

- Strict mode enabled
- Use `type` for type definitions, `interface` for object shapes
- Prefer explicit return types for public APIs
- Use `const` for variables that won't be reassigned
- Run Prettier via `yarn format` before finalizing changes
- Keep functions small; avoid large inline objects in JSX

---

## 6. Naming Conventions

- Components: PascalCase (`UserProfile.tsx`)
- Files: kebab-case for utilities (`user-utils.ts`), PascalCase for components
- Variables: camelCase (`userName`)
- Constants: UPPER_SNAKE_CASE (`API_BASE_URL`)
- Types: PascalCase with `T` prefix for generic types (`TUser`)

---

## 7. Error Handling & Logging

- Use try/catch for async operations
- Return Result types or throw errors consistently
- Log errors with context, never expose stack traces to users
- Avoid swallowing errors without comment or fallback

---

## 8. React Patterns

- Use `'use client'` directive for client components
- Prefer function components with hooks
- Use `React.memo` for expensive components
- Avoid inline functions in render props

---

## 9. Global State Rules (Dashboard Only)

✅ Zustand is the **only** allowed global state mechanism
❌ React Context for shared/global state is forbidden

Allowed only in: src/state/**, src/app/store/**

Rule: If state must survive navigation or be shared → it lives in Zustand.

---

## 10. URL-Synchronized State

Anything involving:

- URL ↔ state
- Editor deep links
- Shareable views

MUST be handled inside Zustand slices.

❌ Forbidden:

- Parsing URL params inside components
- Sync logic inside useEffect

---

## 11. Component State Rules

Allowed:

- useState for local UI only
- useEffect for browser-only effects
- useRef for DOM access

Forbidden:

- useState for cross-component data
- Local state mirroring global state

---

## 12. packages/neurapress Rules (Very Important)

packages/neurapress is treated as a vendored internal library.

MUST:

- Keep its own internal structure
- Use relative imports or package exports
- Remain usable outside this repo
- Export public APIs via: src/index.ts, src/editor/index.ts, src/components/index.ts, src/lib/index.ts

MUST NOT:

- Assume Next.js App Router context
- Introduce app/, page.tsx, layout.tsx dependencies into dashboard
- Introduce Zustand, Context, or global state
- Depend on dashboard-specific CSS or runtime config

---

## 13. Testing Guidelines

- Unit tests: Vitest with jsdom environment
- E2E tests: Playwright
- Test files: `*.test.{ts,tsx}` or `__tests__/**/*`
- Use `describe`, `it`, `expect` from Vitest
- Mock external dependencies in test setup

---

## 14. Environment & Runtime Config

- No new environment variables without approval
- Runtime config must live in: src/config/runtime-service-config\*.yaml
- Runtime config is hydrated in dashboard only
- packages/\* must remain config-agnostic

---

## 15. Cursor / Copilot Rules

- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found

---

## 16. TL;DR for AI Agents

- dashboard = application
- packages = libraries
- Zustand only in dashboard
- No @/ imports inside packages
- Never "fix" libraries by polluting the app
- Always run `yarn lint` and `yarn typecheck` before completing tasks
- If `yarn lint` fails with "Invalid project directory .../lint" (Next 16 CLI), use `./node_modules/.bin/eslint .` instead

---

# Agent Operating Rules

You are an AI agent working inside this repository.

## Role

- Act as a senior engineer and automation assistant.
- Prioritize correctness, minimal changes, and reproducibility.
- agent.md mirrors AGENTS.md; when in doubt, follow AGENTS.md as the source of truth.

## Global Rules

- Do not introduce new dependencies unless explicitly requested.
- Do not change API contracts without explicit instruction.
- Do not add new environment variables without approval.
- Keep changes scoped to the request; avoid unrelated refactors.
- Prefer minimal edits that preserve existing behavior and style.

## Repository Constraints (Quick View)

- App layer: src/app/**, src/components/**, src/lib/**, src/state/**, src/modules/**
- Library layer: packages/** (no @/ aliases, no global state)
- Global state: Zustand only, in src/state/** or src/app/store/**
- URL-synced state must live in Zustand slices

## Testing Policy

- Follow mcp/testing.md for minimal verification.
- Always run the minimal verification after a coherent change-set.

## Output Format

Always respond with:

1. Summary of changes
2. Commands executed
3. Result (success/failure)
4. Next step

If these rules conflict with user instructions, ask once for clarification and proceed conservatively.