From 95d40265c46ee1705db4fd0bf3bdfc3dde45846d Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 25 Feb 2026 16:59:09 +0000
Subject: [PATCH] Add AGENTS.md with Cursor Cloud development instructions

Co-authored-by: Nick Misasi <nick13misasi@gmail.com>
---
 AGENTS.md | 78 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 57 insertions(+), 21 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index dda83dd01bc..f9d4ff9bbf1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,32 +1,68 @@
+# Mattermost Development
+
+Mattermost is an open-source collaboration/messaging platform with a Go backend (`server/`) and React/TypeScript frontend (`webapp/`).
+
 ## Cursor Cloud specific instructions
 
-This is the Mattermost monorepo. The webapp lives under `webapp/`.
+### Services overview
 
-### Environment
+| Service | Description | Port |
+|---------|-------------|------|
+| Mattermost Server (Go) | Backend API + serves webapp | 8065 |
+| PostgreSQL | Primary database | 5432 |
+| Inbucket | Fake email server for testing | 9001 (web), 10025 (SMTP) |
+| Redis | Cache/session store | 6379 |
 
-- Node.js v24+ and npm v11+ are required (managed via nvm).
-- Source nvm before running any node/npm commands: `export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"`
-- Go toolchain is at `/usr/local/go/bin` — add to PATH when needed.
+### Starting Docker services
 
-### webapp dependencies
+Docker must be started manually in Cloud Agent VMs since `systemd` is not running:
 
-- `cd /workspace/webapp && npm install` installs all workspace dependencies.
-- The `postinstall` script automatically builds shared workspaces (`platform/types`, `platform/client`, `platform/components`, `platform/shared`).
+```bash
+sudo dockerd &>/tmp/dockerd.log &
+sleep 3
+sudo chmod 666 /var/run/docker.sock
+```
+
+Then start the required services:
+
+```bash
+cd server && ENABLED_DOCKER_SERVICES="postgres inbucket redis" make start-docker
+```
+
+### Running the server
+
+```bash
+cd server && make run-server
+```
+
+The server runs on port 8065. To verify: `curl -s http://localhost:8065/api/v4/system/ping`
+
+The server's `run-server` target handles `setup-go-work`, `start-docker`, and building the client symlink automatically. If you need to start things separately, ensure `go.work` is set up (`make setup-go-work`) and the `client` symlink exists (`ln -nfs ../webapp/channels/dist client`).
+
+### Building the webapp
+
+```bash
+cd webapp && npm install && make dist
+```
+
+For development with hot-reloading: `cd webapp && make run` (or `make dev` for webpack-dev-server).
+
+### Lint / Style checks
+
+- **Webapp**: `cd webapp && npm run check` (runs ESLint + Stylelint across all workspaces)
+- **Server**: `cd server && go vet ./...`
 
 ### Running tests
 
-#### Go server tests
-- Run from `/workspace/server` with `PATH=/usr/local/go/bin:$PATH`.
-- Example (small package): `go test ./public/model/... -count=1 -short -timeout 120s`
-- The `-short` flag skips long-running integration tests that need a database.
+- **Webapp unit tests**: `cd webapp && npm run test --workspace platform/client` (or any specific workspace)
+- **Server unit tests**: `cd server && go test ./public/model/... -count=1 -short -timeout 120s`
+- Full server tests need database and are slow: `cd server && make test-server`
 
-#### Webapp tests
-- To run tests for a specific workspace, use `npm run test --workspace <name>` from `webapp/`.
-  - Example: `npm run test --workspace platform/client`
-- Do **not** use `npx jest --testPathPatterns="platform/client"` from the root — it picks up both compiled `lib/` tests and uncompiled `src/` TypeScript tests without the correct transform config, causing failures.
-- The `platform/client` workspace has 4 test suites / 27 tests (websocket, client4, helpers, errors).
+### Gotchas
 
-### Linting
-
-- `npm run check` from `webapp/` runs ESLint across all workspaces.
-- Per-workspace: `npm run check --workspace <name>`.
+- The Go version must match `server/.go-version` (currently 1.24.13). The system Go at `/usr/bin/go` may be outdated; use `/usr/local/go/bin/go`.
+- Node.js must match `.nvmrc` (currently 24.11). Use nvm: `nvm use` from the repo root.
+- The webapp uses npm workspaces (not pnpm/yarn). Always use `npm install` from `webapp/`.
+- `make run` in `server/` starts both server and webapp in development mode. The server runs in the background by default (`RUN_SERVER_IN_BACKGROUND=true` in `config.mk`).
+- When running Jest tests, use `npm run test --workspace <name>` rather than calling `npx jest` directly, because the root-level Jest config differs from workspace-level configs (Jest 30 renamed `--testPathPattern` to `--testPathPatterns`).
+- First-time `go run` or `go test` in the server will download many dependencies and can take 60+ seconds.