Add AGENTS.md file for AI coding agent guidance

[Copilot]

Overview

This PR adds an AGENTS.md file to the repository root to provide comprehensive documentation for AI coding agents working on this project. The file follows the agents.md open format standard, which is designed to give coding agents the context and instructions they need to work effectively.

What is AGENTS.md?

AGENTS.md serves as a "README for agents" - a standardized, predictable place to provide technical context and instructions that help AI coding tools understand and contribute to a project. It complements the human-focused README.md by containing detailed technical instructions specifically for automated tools.

Contents

The AGENTS.md file includes comprehensive documentation across the following areas:

Project Overview

• Description of the ChatGPT + Enterprise data RAG application architecture
• npm workspace structure with three main packages (webapp, search, indexer)
• Key technologies: TypeScript, React, Lit, Fastify, Vite, Azure services

Setup & Development

• Prerequisites and installation commands
• First-time Azure deployment with azd up
• Local development workflow (requires Azure deployment first)
• Running services individually or concurrently
• Environment variable management with Azure Developer CLI

Testing

• Unit tests with Node.js test runner and c8 coverage
• E2E tests with Playwright configuration
• Load tests with k6
• Test file locations and specific commands

Code Style & Build

• Linting and formatting with ESLint and Prettier
• Pre-commit hooks with simple-git-hooks
• Building packages and Docker images
• TypeScript compilation and Vite bundling

Deployment

• Azure deployment with azd commands
• Docker containerization for Container Apps
• Static Web App deployment for frontend
• Environment-specific configurations

Additional Context

• npm workspace command patterns
• Common gotchas and troubleshooting tips
• Data reindexing procedures
• Performance considerations
• Backend API compatibility notes

Benefits

This file will help AI coding agents:

• Quickly understand the project architecture and structure
• Execute the correct commands for setup, development, and testing
• Follow the project's code style and conventions
• Navigate the workspace structure effectively
• Deploy and build the application correctly

The file contains actionable, specific commands that agents can execute directly, making it easier for AI tools to contribute to the project without requiring additional human guidance.

Related

Fixes #[issue_number] (Add AGENTS.md file)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add AGENTS.md file</issue_title>
<issue_description>Title: Add AGENTS.md file

Plan

We need to add a specific file named AGENTS.md into this repository. To do that, think through and analyze the following plan. After careful analysis, perform each step exactly as stated.

1. Scan the repository to get a complete understanding of what it contains.
2. Create an AGENTS.md file at the root of the repository if it does not exist. See "## AGENTS.md Instructions" below and follow that general template format based upon what you found in this repository. In addition to the provided template below, research the additional template available at https://github.com/gakeez/agents_md_collection/tree/main/examples so that you understand your options for creating the AGENTS.md file.

RULES:

• ONLY add the AGENTS.md file if it does not already exist. DO NOT modify any other files.
• DO NOT COPY the actual content from the template that is mentioned below. Use the template to understand the format that should be used to create the file.

AGENTS.md Instructions

Create high‑quality AGENTS.md file

You are a code agent. Your task is to create a complete, accurate AGENTS.md at the root of this repository that follows the public guidance at https://agents.md/.

AGENTS.md is an open format designed to provide coding agents with the context and instructions they need to work effectively on a project.

What is AGENTS.md?

AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project. It complements README.md by containing detailed technical context that coding agents need but might clutter a human-focused README.

Key Principles

• Agent-focused: Contains detailed technical instructions for automated tools
• Complements README.md: Doesn't replace human documentation but adds agent-specific context
• Standardized location: Placed at repository root (or subproject roots for monorepos)
• Open format: Uses standard Markdown with flexible structure
• Ecosystem compatibility: Works across 20+ different AI coding tools and agents

File Structure and Content Guidelines

1. Required Setup

• Create the file as AGENTS.md in the repository root
• Use standard Markdown formatting
• No required fields - flexible structure based on project needs

2. Essential Sections to Include

Project Overview

• Brief description of what the project does
• Architecture overview if complex
• Key technologies and frameworks used

Setup Commands

• Installation instructions
• Environment setup steps
• Dependency management commands
• Database setup if applicable

Development Workflow

• How to start development server
• Build commands
• Watch/hot-reload setup
• Package manager specifics (npm, pnpm, yarn, etc.)

Testing Instructions

• How to run tests (unit, integration, e2e)
• Test file locations and naming conventions
• Coverage requirements
• Specific test patterns or frameworks used
• How to run subset of tests or focus on specific areas

Code Style Guidelines

• Language-specific conventions
• Linting and formatting rules
• File organization patterns
• Naming conventions
• Import/export patterns

Build and Deployment

• Build commands and outputs
• Environment configurations
• Deployment steps and requirements
• CI/CD pipeline information

3. Optional but Recommended Sections

Security Considerations

• Security testing requirements
• Secrets management
• Authentication patterns
• Permission models

Monorepo Instructions (if applicable)

• How to work with multiple packages
• Cross-package dependencies
• Selective building/testing
• Package-specific commands

Pull Request Guidelines

• Title format requirements
• Required checks before submission
• Review process
• Commit message conventions

Debugging and Troubleshooting

• Common issues and solutions
• Logging patterns
• Debug configuration
• Performance considerations

Example Template

Use this as a starting template and customize based on the specific project:

# AGENTS.md

## Project Overview

[Brief description of the project, its purpose, and key technologies]

## Setup Commands

- Install dependencies: `[package manager] install`
- Start development server: `[command]`
- Build for production: `[command]`

## Development Workflow

- [Development server startup instructions]
- [Hot reload/watch mode information]
- [Environment variable setup]

## Testing Instructions

- Run all tests: `[command]`
- Run unit tests: `[command]`
- Run integration tests: `[command]`
- Test coverage: `[command]`
- [Specific testing patterns or requirements]

## Code Style

- [Language and framework conventions]
- [Linting rules and commands]
- [Formatting requirements]
- [File orga...

</details>
Fixes Azure-Samples/azure-search-openai-javascript#240

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.