Update project metadata and CI workflow

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "mongodb@claude-plugins-official": true
+  }
+}

.devcontainer/README.md

@@ -0,0 +1,87 @@
+# Codespaces & Dev Container Setup
+
+This project is configured to work seamlessly in GitHub Codespaces or with VS Code Dev Containers.
+
+## Starting with Codespaces
+
+1. **Click "Code" → "Codespaces" → "Create codespace on main"** from the GitHub repo
+2. The devcontainer will automatically:
+   - Spin up a MongoDB instance (Atlas Local)
+   - Install all dependencies
+   - Seed sample data
+
+## Using with VS Code Dev Containers
+
+1. **Install the Dev Containers extension** in VS Code
+2. **Open the repo locally** and run: `Ctrl+Shift+P` → "Dev Containers: Reopen in Container"
+3. VS Code will build the environment and start MongoDB
+
+## Accessing Services
+
+Once the devcontainer is running:
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| React App | http://localhost:5173 | Frontend (Vite dev server) |
+| Express API | http://localhost:5050 | Backend REST API |
+| MongoDB | mongodb://admin:mongodb@localhost:27017 | Database (no browser UI) |
+| MongoDB VS Code Extension | N/A | Query database directly in VS Code |
+
+## Quick Start in Codespaces
+
+Once the devcontainer is fully loaded (wait for "Poststart" to complete):
+
+```bash
+# Terminal 1: Start the Express server
+cd mern/server
+npm start
+
+# Terminal 2: Start the React dev server
+cd mern/client
+npm run dev
+```
+
+Then open http://localhost:5173 in your browser.
+
+## Database Credentials
+
+- **Host**: `mongodb` (inside container) or `localhost:27017` (from host)
+- **Username**: `admin`
+- **Password**: `mongodb`
+- **Database**: `employees`
+
+## Seeding Sample Data
+
+The devcontainer automatically seeds sample data on startup. To manually reseed:
+
+```bash
+cd mern/server
+node seed.js
+```
+
+## VS Code Extensions
+
+The devcontainer includes these extensions:
+
+- **MongoDB for VS Code** — Query your MongoDB directly from VS Code
+- **TypeScript** — TypeScript language support
+- **Prettier** — Code formatter
+
+## Troubleshooting
+
+### MongoDB connection issues
+```bash
+# Check if MongoDB is running
+mongosh -u admin -p mongodb --eval "db.adminCommand('ping')"
+```
+
+### Port conflicts
+If ports 5050, 5173, or 27017 are already in use:
+- **Codespaces**: Automatic port forwarding handles this
+- **Local Dev Container**: Modify `docker-compose.yml` to use different ports
+
+### Rebuild the devcontainer
+```bash
+# VS Code: Ctrl+Shift+P → "Dev Containers: Rebuild Container"
+# CLI: devcontainer build --workspace-folder .
+```

.devcontainer/devcontainer.json

@@ -0,0 +1,48 @@
+{
+  "name": "MERN Stack with MongoDB",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "app",
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "22"
+    }
+  },
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "mongodb.mongodb-vscode",
+        "ms-vscode.vscode-typescript-next",
+        "esbenp.prettier-vscode"
+      ],
+      "settings": {
+        "mongodb.connectionSslEnabled": false,
+        "mongodb.defaultAuthenticationDatabase": "admin"
+      }
+    }
+  },
+
+  "forwardPorts": [5050, 5173, 27017],
+  "portsAttributes": {
+    "5050": {
+      "label": "Express API",
+      "onAutoForward": "notify"
+    },
+    "5173": {
+      "label": "React Dev Server",
+      "onAutoForward": "notify"
+    },
+    "27017": {
+      "label": "MongoDB",
+      "onAutoForward": "silent"
+    }
+  },
+
+  "postCreateCommand": "cd mern/server && npm ci && node seed.js && cd ../client && npm ci",
+
+  "remoteEnv": {
+    "ATLAS_URI": "mongodb://admin:mongodb@mongodb:27017/employees"
+  }
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,34 @@
+version: '3.8'
+
+services:
+  app:
+    image: mcr.microsoft.com/devcontainers/javascript-node:22-bookworm
+    volumes:
+      - ../..:/workspaces:cached
+    command: sleep infinity
+    network_mode: service:mongodb
+    environment:
+      - ATLAS_URI=mongodb://admin:mongodb@mongodb:27017/employees
+      - PORT=5050
+
+  mongodb:
+    image: mongodb/mongodb-atlas-local:latest
+    restart: unless-stopped
+    ports:
+      - 27017:27017
+    environment:
+      MONGODB_INITDB_ROOT_USERNAME: admin
+      MONGODB_INITDB_ROOT_PASSWORD: mongodb
+      MONGO_INITDB_DATABASE: employees
+    volumes:
+      - mongodb-data:/data/db
+      - mongodb-config:/data/configdb
+    healthcheck:
+      test: mongosh --eval "db.adminCommand('ping')"
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  mongodb-data:
+  mongodb-config:

.github/workflows/main.yaml

@@ -1,58 +1,71 @@
-# This is a basic workflow to help you get started with Actions
-
 name: CI
 
-# Controls when the workflow will run
 on:
-  # Triggers the workflow on push or pull request events but only for the main branch
   push:
-    branches: [ $default-branch ]
+    branches: [ main ]
   pull_request:
-    branches: [ $default-branch ]
-
-  # Allows you to run this workflow manually from the Actions tab
+    branches: [ main ]
   workflow_dispatch:
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
-  # This workflow contains a single job called "build"
-
   build:
-    # The type of runner that the job will run on
     runs-on: ubuntu-latest
     environment: Testing
     strategy:
       matrix:
-        node-version: [14.x , 16.x]
-      max-parallel: 1  
-
-    # Steps represent a sequence of tasks that will be executed as part of the job
+        node-version: [20.x, 22.x]
+      max-parallel: 1
+    services:
+      mongodb:
+        image: mongo:latest
+        options: >-
+          --health-cmd mongosh
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 27017:27017
+        env:
+          MONGO_INITDB_ROOT_USERNAME: admin
+          MONGO_INITDB_ROOT_PASSWORD: mongodb
+
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v2
-        with: 
-          ref: 'main-test'
+      - uses: actions/checkout@v4
 
-      - name: Install server npm packages
-        uses: bahmutov/npm-install@v1
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
         with:
-          working-directory: mern/server
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+          cache-dependency-path: |
+            mern/server/package-lock.json
+            mern/client/package-lock.json
+
+      - name: Install server npm packages
+        run: npm ci
+        working-directory: mern/server
 
       - name: Install client npm packages
-        uses: bahmutov/npm-install@v1
-        with:
-          working-directory: mern/client
+        run: npm ci
+        working-directory: mern/client
 
       - name: Start server in the background
-        env: 
-          ATLAS_URI: ${{ secrets.ATLAS_URI }}
-        run: (cd mern/server && echo "ATLAS_URI=$ATLAS_URI" > config.env  && npm start &)
+        env:
+          ATLAS_URI: mongodb://admin:mongodb@localhost:27017/
+        run: |
+          echo "ATLAS_URI=$ATLAS_URI" > config.env
+          npm start > /tmp/server.log 2>&1 &
+          echo "Server PID: $!"
+        working-directory: mern/server
 
-      - name: Start React app in the background
-        run: (cd mern/client && npm start &)
+      - name: Wait for server to be ready
+        run: |
+          npx wait-on http://localhost:5050/record --timeout 30000 || (cat /tmp/server.log && exit 1)
 
       - name: Install Cypress and run tests
-        uses: cypress-io/github-action@v2
+        uses: cypress-io/github-action@v6
         with:
           working-directory: mern/client
+          start: npm run dev
+          wait-on: 'http://localhost:5173'
 

AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md — AI Agent Guide
+
+This file is the source of truth for AI agents working in this repository.
+
+## Project Overview
+
+Full-stack MERN CRUD app for managing employee records. React (Vite) frontend communicates with an Express REST API; MongoDB Atlas stores data in the `employees` database, `records` collection.
+
+## Project Structure
+
+```
+mern-stack-example/
+├── EDD.md                          # MongoDB data model — read before touching schema or routes
+├── mern/
+│   ├── client/                     # React 18 + Vite + Tailwind CSS frontend
+│   │   ├── src/
+│   │   │   ├── App.jsx             # Root component and routes
+│   │   │   ├── components/
+│   │   │   │   ├── Navbar.jsx
+│   │   │   │   ├── Record.jsx      # Create / edit form
+│   │   │   │   └── RecordList.jsx  # Main list view
+│   │   ├── vite.config.js
+│   │   └── package.json
+│   └── server/                     # Node.js + Express REST API
+│       ├── db/
+│       │   └── connection.js       # MongoDB Atlas connection (appName set here)
+│       ├── routes/
+│       │   └── record.js           # GET / POST / PATCH / DELETE /record
+│       ├── seed.js                 # Database seed script
+│       ├── server.js               # Express app entry point
+│       └── package.json
+└── .github/workflows/main.yaml     # CI: install, start, Cypress e2e
+```
+
+## Build and Test Commands
+
+```bash
+# Install and start the API server
+cd mern/server
+npm install
+npm start           # requires mern/server/config.env (see Environment Variables)
+
+# Install and start the React dev server
+cd mern/client
+npm install
+npm run dev         # serves on http://localhost:5173
+
+# Seed the database
+cd mern/server
+node seed.js        # requires ATLAS_URI in config.env
+
+# Run Cypress e2e tests (client must be running)
+cd mern/client
+npx cypress run
+```
+
+## Environment Variables
+
+Create `mern/server/config.env` (not committed):
+
+| Variable    | Description                              | Example |
+|-------------|------------------------------------------|---------|
+| `ATLAS_URI` | MongoDB Atlas connection string          | `mongodb+srv://user:pass@cluster.mongodb.net/` |
+| `PORT`      | Port for the Express server              | `5050`  |
+
+## MongoDB Skills
+
+Use the official MongoDB agent skills from https://github.com/mongodb/agent-skills
+whenever the task is MongoDB-specific and a matching skill exists.
+
+## When To Use EDD.md
+
+Use [EDD.md](./EDD.md) as the source of truth for the MongoDB data model in this repository.
+
+Consult [EDD.md](./EDD.md) before making changes that touch:
+
+- MongoDB collections, document structure, or field names
+- Express routes that read or write database records
+- Validation, form fields, API payloads, or UI that depend on persisted data
+- Schema documentation, Mermaid diagrams, or entity modeling discussions