deep-research: Instructions file for Codex

AGENTS.md

This document provides essential guidelines and technical references for AI agents (and human developers) working on the Deep Research repository. Adhere to these patterns to ensure consistency, security, and maintainability.

---

🚀 Development Workflow & Commands

The project uses pnpm as the primary package manager.

Core Commands

• Install Dependencies: pnpm install
• Development Server: pnpm dev (Runs at http://localhost:3000)
• Build Project: pnpm build
• Static Export: pnpm build:export (Generates out/ directory)
• Standalone Build: pnpm build:standalone
• Linting: pnpm lint

Testing

• Status: Currently, there are no automated tests in the codebase.
• Guideline: If adding tests, use Vitest or Jest following standard Next.js patterns. Place test files next to the code they test (e.g., ComponentName.test.tsx) or in a __tests__ directory.
• Single Test: To run a single test (if added), use pnpm vitest run path/to/file.test.ts.

---

📂 Project Structure

• src/app: Next.js App Router (Pages, API routes, Layouts).
• src/components: UI components.
  • ui/: Shadcn primitives.
  • Internal/: Custom shared components.
  • Research/, Knowledge/, etc.: Feature-specific components.
• src/hooks: Custom React hooks for business logic and state interaction.
• src/libs: External service integrations (e.g., MCP server logic).
• src/store: Zustand stores for global state and persistence.
• src/utils: Helper functions and core deep research logic.
• src/locales: I18n translation files (JSON).

---

🎨 Code Style & Conventions

1. TypeScript & Types

• Strict Mode: strict: true is enabled in tsconfig.json. Always provide explicit types for function parameters and return values.
• Global Types: Core business logic types (e.g., SearchTask, Knowledge, Source) are defined in src/types.d.ts. Check this file before creating new interfaces.
• Explicit Any: While @typescript-eslint/no-explicit-any is currently off, avoid any unless absolutely necessary for external library compatibility. Prefer unknown or specific interfaces.
• Zod: Use Zod for schema validation, especially for AI response parsing and API request bodies. See src/app/api/mcp/server.ts for examples.