# docs/AGENTS.md

Documentation authoring guidance for AI coding assistants.

This directory contains the project's architecture and usage documentation built with MkDocs.

## Directory Structure

```
docs/
├── mkdocs.yml          # MkDocs configuration
├── base.yml            # Base configuration
├── Makefile            # Doc build automation
├── requirements.txt    # Doc dependencies
├── theme/              # Custom theme assets
└── docs/               # Documentation content
    ├── index.md        # Home page
    ├── architecture/   # System design, ADRs, plugins, security
    ├── deployment/     # Docker, K8s, cloud guides
    ├── development/    # Developer guides, building, testing
    ├── manage/         # Operations, API usage, logging, scaling
    ├── using/          # User guides (agents, clients, servers)
    ├── testing/        # Test guides, performance, fuzzing
    ├── best-practices/ # Best practice guides
    ├── tutorials/      # Step-by-step tutorials
    ├── overview/       # Project overview
    ├── faq/            # FAQ
    └── coverage/       # Generated coverage reports
```

## Quick Commands

From `docs/` directory:

```bash
# Install dependencies
pip install -r requirements.txt

# Build docs
make build                # Build static site

# Serve locally
make serve                # Serve at http://localhost:8003 (configured in docs/base.yml)

# Clean
make clean                # Remove build artifacts
```

From repository root:

```bash
make docs                 # Build documentation
# For local serving, run from docs/:
#   cd docs && make serve
```

## Writing Documentation

### File Location

Place documentation in the appropriate subdirectory:

| Topic | Directory |
|-------|-----------|
| System design, ADRs | `docs/architecture/` |
| Deployment guides | `docs/deployment/` |
| Developer guides | `docs/development/` |
| Operations guides | `docs/manage/` |
| User guides | `docs/using/` |
| Test documentation | `docs/testing/` |

### Markdown Conventions

- Use ATX-style headers (`#`, `##`, `###`)
- Include front matter for navigation title if needed
- Use fenced code blocks with language hints
- Keep lines under 120 characters when practical

### Code Examples

Use fenced code blocks with language identifier:

```python
from mcpgateway import Gateway

gateway = Gateway()
gateway.start()
```

### Admonitions

```markdown
!!! note
    This is a note.

!!! warning
    This is a warning.

!!! tip
    This is a tip.
```

### Internal Links

```markdown
See [Configuration Reference](manage/configuration.md) for details.
See [Architecture Overview](architecture/index.md).
```

## Navigation

Navigation is configured in `mkdocs.yml`. When adding new pages:

1. Create the markdown file in the appropriate directory
2. Add an entry to the `nav` section in `mkdocs.yml`

## API Documentation

API documentation is auto-generated from OpenAPI schema:
- Swagger UI: `http://localhost:4444/docs`
- OpenAPI JSON: `http://localhost:4444/openapi.json`

## Coverage Reports

Coverage reports are generated to `docs/docs/coverage/`:

```bash
make htmlcov              # Generate HTML coverage report
```

## Key Documentation Pages

- `docs/development/developer-onboarding.md` - New contributor guide
- `docs/development/building.md` - Build system and testing
- `docs/manage/api-usage.md` - REST API guide
- `docs/architecture/index.md` - Architecture overview
- `docs/architecture/adr/` - Architecture Decision Records

## Important Notes

- Do not create documentation files unless explicitly requested
- Prefer editing existing files over creating new ones
- Keep documentation up-to-date with code changes
- Use relative links for internal references
