docs: Update AGENTS.md

[overcut-ai]

Summary

Refreshes AGENTS.md with the latest knowledge an AI contributor needs to work safely within the monorepo.

Changes

• Document each service, core stack, and supporting infrastructure at a glance
• Outline directory conventions, naming expectations, and safe extension points
• Capture development workflows, validation requirements, and tool usage rules for contributors

Why

Keeping AGENTS.md synchronized with the repository structure ensures automation agents have clear guardrails and context before making changes.

Summary

This PR refreshes AGENTS.md to equip automation contributors with an up-to-date overview of the monorepo’s services, tooling, and development workflows. The guide now captures stack conventions, environment setup expectations, and best practices needed to work safely across ecommerce and logistics applications.

Changes

• Documentation: Added a comprehensive AGENTS guide detailing each service’s stack, authentication model, and messaging responsibilities.
• Documentation: Documented repository structure, naming conventions, and safe extension points for backend and frontend modules.
• Documentation: Captured per-service scripts, common workflows, testing guidance, and critical rules/resources for contributors.

Commits

• 5ad3933 docs: update AGENTS.md

Testing

• Review AGENTS.md to ensure described services, scripts, and paths align with the current repository layout.
• Confirm markdown tables, lists, and code blocks render correctly on GitHub.
• Validate referenced README files and directories exist and remain accurate.

[overcut-ai]

Completed Working on "Auto PR Description"

✅ Workflow completed successfully.

---

👉 View complete log

[overcut-ai]

Completed Working on "Code Review"

✅ Workflow completed successfully.

---

👉 View complete log

[overcut-ai]

Totals: 0 BLOCKER / 0 CRITICAL / 1 MAJOR / 2 MINOR.

Key themes:

1. AGENTS.md over-promises available setup artifacts (e.g., .env.example, docker-compose files) leading to broken onboarding steps.
2. Testing guidance references Jest config files that do not exist, so contributors cannot follow the documented workflow.

Next steps:

• Either add the missing .env.example templates and docker-compose manifests that the guide references, or update AGENTS.md to describe the actual files and workflows that exist today.
• Align the testing section with the real Jest configuration locations (currently in each package.json) or add the referenced jest.config.ts files.

[overcut-ai]

[major]: The "Run ecommerce-server locally" instructions tell agents to copy .env.example to .env, but none of the services actually include .env.example—only committed .env files—so the very first setup command fails. Suggested fix: add .env.example templates for each service or update the guide to direct agents to edit the existing .env files directly.

[overcut-ai]

[minor]: The Environment section claims every service ships .env, Dockerfile, docker-compose.yml, and docker-compose.dev.yml, but the frontend at apps/ecommerce-admin only has .env and a Dockerfile, so contributors are told to rely on compose manifests that do not exist. Suggested fix: scope the statement to the backend services or add the missing compose files for the admin client.

[overcut-ai]

[minor]: The Testing section states that Jest is configured per service via apps/*/jest.config.ts, but no such files exist—the Jest configuration lives inside each package.json. This misleads contributors trying to adjust tests. Suggested fix: either add the referenced jest.config.ts files or update the text to explain that Jest is configured via the jest block in each package.json.