{"owner":"u14app","repo":"deep-research","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis 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.\n\n---\n\n## 🚀 Development Workflow & Commands\n\nThe project uses **pnpm** as the primary package manager.\n\n### Core Commands\n\n- **Install Dependencies**: `pnpm install`\n- **Development Server**: `pnpm dev` (Runs at `http://localhost:3000`)\n- **Build Project**: `pnpm build`\n- **Static Export**: `pnpm build:export` (Generates `out/` directory)\n- **Standalone Build**: `pnpm build:standalone`\n- **Linting**: `pnpm lint`\n\n### Testing\n\n- **Status**: Currently, there are no automated tests in the codebase.\n- **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.\n- **Single Test**: To run a single test (if added), use `pnpm vitest run path/to/file.test.ts`.\n\n---\n\n## 📂 Project Structure\n\n- `src/app`: Next.js App Router (Pages, API routes, Layouts).\n- `src/components`: UI components.\n  - `ui/`: Shadcn primitives.\n  - `Internal/`: Custom shared components.\n  - `Research/`, `Knowledge/`, etc.: Feature-specific components.\n- `src/hooks`: Custom React hooks for business logic and state interaction.\n- `src/libs`: External service integrations (e.g., MCP server logic).\n- `src/store`: Zustand stores for global state and persistence.\n- `src/utils`: Helper functions and core deep research logic.\n- `src/locales`: I18n translation files (JSON).\n\n---\n\n## 🎨 Code Style & Conventions\n\n### 1. TypeScript & Types\n\n- **Strict Mode**: `strict: true` is enabled in `tsconfig.json`. Always provide explicit types for function parameters and return values.\n- **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.\n- **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.\n- **Zod**: Use **Zod** for schema validation, especially for AI response parsing and API request bodies. See `src/app/api/mcp/server.ts` for examples.\n\n### 2. React & Next.js\n\n- **App Router**: This project uses the Next.js App Router.\n- **Client Components**: Use `\"use client\";` at the top of files that require browser APIs or React hooks (state, effects).\n- **Dynamic Imports**: Use Next.js `dynamic()` for heavy components or those that rely on browser-only libraries (e.g., `MagicDown`, `Mermaid`).\n- **Hooks**: Prefer custom hooks for complex logic (e.g., `useDeepResearch`, `useKnowledge`).\n\n### 3. Components & UI\n\n- **Shadcn UI**: UI primitives are located in `@/components/ui`. Do not modify them directly; extend them or create wrappers in `src/components/Internal`.\n- **Styling**: Use **Tailwind CSS**. Follow mobile-first responsive design patterns.\n- **Icons**: Use **lucide-react**.\n- **I18n**: All UI strings must use `useTranslation` from `react-i18next`. Use `t(\"key.path\")` for all labels.\n\n### 4. State Management\n\n- **Zustand**: Used for global state and persistence.\n- **Persistence**: Most stores use the `persist` middleware (e.g., `useTaskStore` in `src/store/task.ts`) to save research data in `localStorage`.\n- **Radash**: Use **radash** utilities for common operations like `pick`, `isString`, `isObject`, etc.\n\n### 5. Imports\n\n- **Path Alias**: Always use the `@/` prefix for absolute imports from the `src` directory.\n- **Ordering**:\n  1. React/Next.js core\n  2. Third-party libraries\n  3. Components (Internal/UI)\n  4. Hooks & Stores\n  5. Utils & Types\n\n---\n\n## 🛠 Backend & API Patterns\n\n### 1. Error Handling\n\n- Use the `parseError` utility from `@/utils/error.ts` to standardize error messages.\n- In async functions, use `try...catch...finally` to manage loading states and error reporting.\n- Standardized API error format: `{ isError: true, content: [{ type: \"text\", text: \"...\" }] }`.\n\n### 2. API Routes\n\n- **SSE API**: Located at `src/app/api/sse`. Handles real-time streaming research reports.\n- **MCP Server**: Located at `src/app/api/mcp`. Implements the Model Context Protocol for tool use by other AI agents.\n- **Proxying**: The project proxies various AI and search providers via `next.config.ts` rewrites to avoid CORS issues and manage keys.\n\n### 3. Environment Variables\n\n- Refer to `env.tpl` for all available environment variables.\n- Critical variables include `GOOGLE_GENERATIVE_AI_API_KEY`, `TAVILY_API_BASE_URL`, and `ACCESS_PASSWORD`.\n- Never commit `.env` or `.env.local` files.\n\n---\n\n## 🔒 Security & Safety\n\n- **Secrets**: Do not hardcode API keys or credentials.\n- **Sanitization**: Use Zod to sanitize and validate all external inputs (web search results, user input).\n- **Destructive Actions**: Avoid `rm -rf` or history rewriting in git unless explicitly requested.\n\n---\n\n## 🤖 Agent Instructions\n\n- **Read First**: Always read the relevant file and its neighbors before proposing edits.\n- **Follow Patterns**: If adding a new component, look at `src/components/Research/SearchResult.tsx` for a reference implementation.\n- **Keep it Focused**: Make small, cohesive changes. Avoid unrelated refactors.\n- **Validate**: Run `pnpm lint` and `pnpm build` to ensure your changes don't break the build.\n- **Communication**: Summarize what changed, where, and why. Call out tradeoffs, assumptions, and known limitations. If validation could not be run, say so explicitly.\n- **Clarity**: Prefer clarity and simplicity over cleverness. Preserve existing behavior unless the task explicitly requires changes.\n- **UI Consistency**: Ensure all new UI elements support both light and dark modes using Tailwind `dark:` classes.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis 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.\n\n---\n\n## 🚀 Development Workflow & Commands\n\nThe project uses **pnpm** as the primary package manager.\n\n### Core Commands\n\n- **Install Dependencies**: `pnpm install`\n- **Development Server**: `pnpm dev` (Runs at `http://localhost:3000`)\n- **Build Project**: `pnpm build`\n- **Static Export**: `pnpm build:export` (Generates `out/` directory)\n- **Standalone Build**: `pnpm build:standalone`\n- **Linting**: `pnpm lint`\n\n### Testing\n\n- **Status**: Currently, there are no automated tests in the codebase.\n- **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.\n- **Single Test**: To run a single test (if added), use `pnpm vitest run path/to/file.test.ts`.\n\n---\n\n## 📂 Project Structure\n\n- `src/app`: Next.js App Router (Pages, API routes, Layouts).\n- `src/components`: UI components.\n  - `ui/`: Shadcn primitives.\n  - `Internal/`: Custom shared components.\n  - `Research/`, `Knowledge/`, etc.: Feature-specific components.\n- `src/hooks`: Custom React hooks for business logic and state interaction.\n- `src/libs`: External service integrations (e.g., MCP server logic).\n- `src/store`: Zustand stores for global state and persistence.\n- `src/utils`: Helper functions and core deep research logic.\n- `src/locales`: I18n translation files (JSON).\n\n---\n\n## 🎨 Code Style & Conventions\n\n### 1. TypeScript & Types\n\n- **Strict Mode**: `strict: true` is enabled in `tsconfig.json`. Always provide explicit types for function parameters and return values.\n- **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.\n- **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.\n- **Zod**: Use **Zod** for schema validation, especially for AI response parsing and API request bodies. See `src/app/api/mcp/server.ts` for examples.\n\n### 2. React & Next.js\n\n- **App Router**: This project uses the Next.js App Router.\n- **Client Components**: Use `\"use client\";` at the top of files that require browser APIs or React hooks (state, effects).\n- **Dynamic Imports**: Use Next.js `dynamic()` for heavy components or those that rely on browser-only libraries (e.g., `MagicDown`, `Mermaid`).\n- **Hooks**: Prefer custom hooks for complex logic (e.g., `useDeepResearch`, `useKnowledge`).\n\n### 3. Components & UI\n\n- **Shadcn UI**: UI primitives are located in `@/components/ui`. Do not modify them directly; extend them or create wrappers in `src/components/Internal`.\n- **Styling**: Use **Tailwind CSS**. Follow mobile-first responsive design patterns.\n- **Icons**: Use **lucide-react**.\n- **I18n**: All UI strings must use `useTranslation` from `react-i18next`. Use `t(\"key.path\")` for all labels.\n\n### 4. State Management\n\n- **Zustand**: Used for global state and persistence.\n- **Persistence**: Most stores use the `persist` middleware (e.g., `useTaskStore` in `src/store/task.ts`) to save research data in `localStorage`.\n- **Radash**: Use **radash** utilities for common operations like `pick`, `isString`, `isObject`, etc.\n\n### 5. Imports\n\n- **Path Alias**: Always use the `@/` prefix for absolute imports from the `src` directory.\n- **Ordering**:\n  1. React/Next.js core\n  2. Third-party libraries\n  3. Components (Internal/UI)\n  4. Hooks & Stores\n  5. Utils & Types\n\n---\n\n## 🛠 Backend & API Patterns\n\n### 1. Error Handling\n\n- Use the `parseError` utility from `@/utils/error.ts` to standardize error messages.\n- In async functions, use `try...catch...finally` to manage loading states and error reporting.\n- Standardized API error format: `{ isError: true, content: [{ type: \"text\", text: \"...\" }] }`.\n\n### 2. API Routes\n\n- **SSE API**: Located at `src/app/api/sse`. Handles real-time streaming research reports.\n- **MCP Server**: Located at `src/app/api/mcp`. Implements the Model Context Protocol for tool use by other AI agents.\n- **Proxying**: The project proxies various AI and search providers via `next.config.ts` rewrites to avoid CORS issues and manage keys.\n\n### 3. Environment Variables\n\n- Refer to `env.tpl` for all available environment variables.\n- Critical variables include `GOOGLE_GENERATIVE_AI_API_KEY`, `TAVILY_API_BASE_URL`, and `ACCESS_PASSWORD`.\n- Never commit `.env` or `.env.local` files.\n\n---\n\n## 🔒 Security & Safety\n\n- **Secrets**: Do not hardcode API keys or credentials.\n- **Sanitization**: Use Zod to sanitize and validate all external inputs (web search results, user input).\n- **Destructive Actions**: Avoid `rm -rf` or history rewriting in git unless explicitly requested.\n\n---\n\n## 🤖 Agent Instructions\n\n- **Read First**: Always read the relevant file and its neighbors before proposing edits.\n- **Follow Patterns**: If adding a new component, look at `src/components/Research/SearchResult.tsx` for a reference implementation.\n- **Keep it Focused**: Make small, cohesive changes. Avoid unrelated refactors.\n- **Validate**: Run `pnpm lint` and `pnpm build` to ensure your changes don't break the build.\n- **Communication**: Summarize what changed, where, and why. Call out tradeoffs, assumptions, and known limitations. If validation could not be run, say so explicitly.\n- **Clarity**: Prefer clarity and simplicity over cleverness. Preserve existing behavior unless the task explicitly requires changes.\n- **UI Consistency**: Ensure all new UI elements support both light and dark modes using Tailwind `dark:` classes.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis 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.\n\n---\n\n## 🚀 Development Workflow & Commands\n\nThe project uses **pnpm** as the primary package manager.\n\n### Core Commands\n\n- **Install Dependencies**: `pnpm install`\n- **Development Server**: `pnpm dev` (Runs at `http://localhost:3000`)\n- **Build Project**: `pnpm build`\n- **Static Export**: `pnpm build:export` (Generates `out/` directory)\n- **Standalone Build**: `pnpm build:standalone`\n- **Linting**: `pnpm lint`\n\n### Testing\n\n- **Status**: Currently, there are no automated tests in the codebase.\n- **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.\n- **Single Test**: To run a single test (if added), use `pnpm vitest run path/to/file.test.ts`.\n\n---\n\n## 📂 Project Structure\n\n- `src/app`: Next.js App Router (Pages, API routes, Layouts).\n- `src/components`: UI components.\n  - `ui/`: Shadcn primitives.\n  - `Internal/`: Custom shared components.\n  - `Research/`, `Knowledge/`, etc.: Feature-specific components.\n- `src/hooks`: Custom React hooks for business logic and state interaction.\n- `src/libs`: External service integrations (e.g., MCP server logic).\n- `src/store`: Zustand stores for global state and persistence.\n- `src/utils`: Helper functions and core deep research logic.\n- `src/locales`: I18n translation files (JSON).\n\n---\n\n## 🎨 Code Style & Conventions\n\n### 1. TypeScript & Types\n\n- **Strict Mode**: `strict: true` is enabled in `tsconfig.json`. Always provide explicit types for function parameters and return values.\n- **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.\n- **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.\n- **Zod**: Use **Zod** for schema validation, especially for AI response parsing and API request bodies. See `src/app/api/mcp/server.ts` for examples.\n\n### 2. React & Next.js\n\n- **App Router**: This project uses the Next.js App Router.\n- **Client Components**: Use `\"use client\";` at the top of files that require browser APIs or React hooks (state, effects).\n- **Dynamic Imports**: Use Next.js `dynamic()` for heavy components or those that rely on browser-only libraries (e.g., `MagicDown`, `Mermaid`).\n- **Hooks**: Prefer custom hooks for complex logic (e.g., `useDeepResearch`, `useKnowledge`).\n\n### 3. Components & UI\n\n- **Shadcn UI**: UI primitives are located in `@/components/ui`. Do not modify them directly; extend them or create wrappers in `src/components/Internal`.\n- **Styling**: Use **Tailwind CSS**. Follow mobile-first responsive design patterns.\n- **Icons**: Use **lucide-react**.\n- **I18n**: All UI strings must use `useTranslation` from `react-i18next`. Use `t(\"key.path\")` for all labels.\n\n### 4. State Management\n\n- **Zustand**: Used for global state and persistence.\n- **Persistence**: Most stores use the `persist` middleware (e.g., `useTaskStore` in `src/store/task.ts`) to save research data in `localStorage`.\n- **Radash**: Use **radash** utilities for common operations like `pick`, `isString`, `isObject`, etc.\n\n### 5. Imports\n\n- **Path Alias**: Always use the `@/` prefix for absolute imports from the `src` directory.\n- **Ordering**:\n  1. React/Next.js core\n  2. Third-party libraries\n  3. Components (Internal/UI)\n  4. Hooks & Stores\n  5. Utils & Types\n\n---\n\n## 🛠 Backend & API Patterns\n\n### 1. Error Handling\n\n- Use the `parseError` utility from `@/utils/error.ts` to standardize error messages.\n- In async functions, use `try...catch...finally` to manage loading states and error reporting.\n- Standardized API error format: `{ isError: true, content: [{ type: \"text\", text: \"...\" }] }`.\n\n### 2. API Routes\n\n- **SSE API**: Located at `src/app/api/sse`. Handles real-time streaming research reports.\n- **MCP Server**: Located at `src/app/api/mcp`. Implements the Model Context Protocol for tool use by other AI agents.\n- **Proxying**: The project proxies various AI and search providers via `next.config.ts` rewrites to avoid CORS issues and manage keys.\n\n### 3. Environment Variables\n\n- Refer to `env.tpl` for all available environment variables.\n- Critical variables include `GOOGLE_GENERATIVE_AI_API_KEY`, `TAVILY_API_BASE_URL`, and `ACCESS_PASSWORD`.\n- Never commit `.env` or `.env.local` files.\n\n---\n\n## 🔒 Security & Safety\n\n- **Secrets**: Do not hardcode API keys or credentials.\n- **Sanitization**: Use Zod to sanitize and validate all external inputs (web search results, user input).\n- **Destructive Actions**: Avoid `rm -rf` or history rewriting in git unless explicitly requested.\n\n---\n\n## 🤖 Agent Instructions\n\n- **Read First**: Always read the relevant file and its neighbors before proposing edits.\n- **Follow Patterns**: If adding a new component, look at `src/components/Research/SearchResult.tsx` for a reference implementation.\n- **Keep it Focused**: Make small, cohesive changes. Avoid unrelated refactors.\n- **Validate**: Run `pnpm lint` and `pnpm build` to ensure your changes don't break the build.\n- **Communication**: Summarize what changed, where, and why. Call out tradeoffs, assumptions, and known limitations. If validation could not be run, say so explicitly.\n- **Clarity**: Prefer clarity and simplicity over cleverness. Preserve existing behavior unless the task explicitly requires changes.\n- **UI Consistency**: Ensure all new UI elements support both light and dark modes using Tailwind `dark:` classes.\n","category":"root","tokens":1470}]}