──────

### Summary of Changes
  1. Documentation Consolidation:
      • Relocated the docs/ folder and all repository .md files (README.md, DEPLOYMENT.md, DOCKER_README.md,
      DOMAINS_README.md, GETTING_STARTED.md, CI_CD_PORTAINER_GUIDE.md, ADMIN_DEPLOYMENT_SUMMARY.md,
      SECURITY_PRIVATE_FILES.md, handoff.md, azure-project-plan.md, plus service-specific READMEs) into .
      • Updated document links in README.md.
  2. AI Agent Project Map:
      • Created PROJECT_MAP.md in the project root containing complete architecture diagrams, service specs, ports, DB
      schemas, environment variables, and developer workflows.
      • Added PROJECT_MAP.md to .gitignore.
  3. Monitoring UI & Infrastructure Integration:
      • Added monitoring_ui service to docker-compose.yml (port 5175).
      • Configured Gitea workflow docker-build.yml for monitoring_ui builds.
      • Added CORS middleware headers in index.js.
      • Added nginx.conf copy step in Dockerfile.

  ──────
  ### Recommended Commit Message

    docs: consolidate project documentation into monitoring_ui and add agent project map

    - Move all markdown documentation files and docs/ folder into monitoring_ui/docs/
    - Update documentation hub index (monitoring_ui/docs/README.md) with relative paths
    - Generate comprehensive AI agent reference map (PROJECT_MAP.md) in repository root
    - Add PROJECT_MAP.md and monitoring_ui build output/env overrides to .gitignore
    - Integrate monitoring_ui service into docker-compose.yml and Gitea CI workflow
    - Configure CORS handling in employee_api for monitoring dashboard access
    ──────
  ### Alternative Short Commit Message

    refactor(docs): move docs to monitoring_ui and create AI agent PROJECT_MAP.md

.github/agents/azure-project-integrate/references/end-to-end.md

@@ -0,0 +1,40 @@
+<!-- azure-cor-disclaimer -->
+> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.
+
+# End-to-End Wire-Up Verification
+
+> Read at **Step 4**. How to run the frontend and backend together and prove they communicate.
+
+---
+
+## Run both processes concurrently (cross-platform)
+
+Start each in its own terminal (async), never with shell-specific backgrounding (`&`, `Start-Job` chains):
+
+1. **Backend** — the run command from the artifact, e.g. `func start` (cwd = backend folder). Wait until the host prints that all functions registered.
+2. **Frontend** — `npm --prefix services/web run dev` (cwd-independent). Wait until the dev server prints its local URL.
+
+The frontend dev proxy (configured in Step 3) forwards `/api` to the backend, so the two talk over `localhost`.
+
+---
+
+## Prove the wiring
+
+You need **at least one real `/api/...` request from the frontend that hits the backend and returns `200` with live data** — not a mock placeholder. Any one of:
+
+- **Logs**: the backend host logs an incoming `GET /api/...` → `200` that originated from the dev server (not your manual curl).
+- **Browser**: load a page with the browser tool; confirm it renders data that came from the backend (and that the network panel shows the `/api` call succeeding). The data must match what the empty-schema backend returns (often an empty list rendering the "empty" state — that is still a valid live response, distinct from mock content).
+- **Write path** (if the app has one): perform a create/update in the UI; confirm the backend receives it and the UI reflects the result.
+
+---
+
+## Capture evidence & shut down
+
+- Record the proof: the request path, method, and status (e.g. `GET /api/users → 200`) that demonstrates frontend → backend wiring.
+- Stop both processes cleanly when done (do not leave servers running).
+
+---
+
+## Distinguishing live from mock
+
+If a page still shows the scaffold's mock content (named demo records, lorem data) while the backend DB is empty, the frontend is **still on mock data** — return to Step 3. A correctly wired app against an empty schema typically shows empty/loading states populated by real (empty) responses, or real data you created via a write path.

.github/agents/azure-project-integrate/references/migrations.md

@@ -0,0 +1,54 @@
+<!-- azure-cor-disclaimer -->
+> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.
+
+# Schema Migrations (NO seed data)
+
+> Read at **Step 1**. Canonical guidance for creating SQL / PostgreSQL schema migrations during integration. **Schema only — never seed data.**
+
+---
+
+## The one hard rule
+
+You create **structure**, not **content**. Allowed: `CREATE TABLE`, `ALTER TABLE`, constraints, indexes, the migration runner. **Forbidden:** `INSERT`, demo rows, and any file/folder/function named `seed`, `seeds`, `seed-data`, `fixtures`. If the scaffold already produced seed files, leave them where they are — do not extend, run, or depend on them.
+
+---
+
+## Per-stack migration tool
+
+| Stack | Tool | Create | Apply | Roll back |
+|-------|------|--------|-------|-----------|
+| Node.js / TypeScript | Knex | `knex migrate:make <name>` | `knex migrate:latest` | `knex migrate:rollback` |
+| Python | Alembic | `alembic revision -m "<name>"` | `alembic upgrade head` | `alembic downgrade -1` |
+| C# / .NET | EF Core | `dotnet ef migrations add <Name>` | `dotnet ef database update` | `dotnet ef database update <Prev>` |
+
+Add the apply/rollback commands as scripts (`"migrate"`, `"migrate:rollback"`) if the scaffold did not.
+
+---
+
+## Every migration file MUST contain real code
+
+- A complete `up()` (or `upgrade()`): `CREATE TABLE` with **all** columns and types the handlers use.
+- A complete `down()` (or `downgrade()`): reverses the `up()` (`DROP TABLE`, etc.).
+- After writing, **list the directory and confirm each file is > 0 bytes**. An empty migration file does not satisfy Step 1.
+
+## Constraints to include (Step 1 requires these)
+
+| Constraint | When |
+|-----------|------|
+| `UNIQUE` | Business-unique fields (email, slug, external id) |
+| `FOREIGN KEY … ON DELETE` | Every relationship; choose `CASCADE` / `SET NULL` deliberately |
+| `CHECK` | Enum-like columns (status, role) |
+| `INDEX` | Columns used in `WHERE` / `JOIN` / `ORDER BY` |
+| `NOT NULL` + sensible defaults | Required columns; timestamps default to `now()` |
+
+## Derive the schema from real usage
+
+Read the handler data-access code (and the entity types) before writing columns — the table must match what the code actually reads and writes. Cross-reference every table name against the collection/table names the handlers use (a `collectionToTable` map if one exists). A mismatch here is the #1 cause of `relation "X" does not exist` at smoke-test time.
+
+## Apply, then prove
+
+1. Start the local database / emulator if the artifact documents one.
+2. Run the apply command. Expect zero errors.
+3. Confirm the tables now exist (the migration tool's status command, or a `\dt` against the local DB).
+
+The proof that migrations are correct is **Step 2's smoke test passing** — handlers querying these tables must not 500.

.github/agents/azure-project-integrate/references/smoke-test.md

@@ -0,0 +1,53 @@
+<!-- azure-cor-disclaimer -->
+> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.
+
+# Backend Smoke Test
+
+> Read at **Step 2**. How to start the backend and prove every endpoint registers and responds.
+
+---
+
+## Per-runtime start command
+
+| Runtime | Build | Start host | Default port |
+|---------|-------|-----------|--------------|
+| Azure Functions (Node v4 / TS) | `npm run build` | `func start` | 7071 |
+| Azure Functions (Python v2) | `python -m py_compile` (or build) | `func start` | 7071 |
+| Azure Functions (.NET isolated) | `dotnet build` | `func start` (or `dotnet run`) | 7071 |
+| Plain Node API | `npm run build` | `npm start` | project-defined |
+
+Run the exact command the artifact (`.azure/integration-plan.md`) documents — it reflects the real project.
+
+---
+
+## Before starting: config & build
+
+- Ensure `.env` / `local.settings.json` has the values the host needs — especially the **DB connection string** pointing at the local database from Step 1. Use `.env.example` as the template. Never commit secrets.
+- Build first. Zero errors. `TS2307: Cannot find module '@app/shared'` → the shared package exports/build are broken; fix before starting.
+- For Functions Node v4: list `dist/` and confirm the `main` glob matches the compiled handler paths. A parent `rootDir` nests output one level deeper (`dist/functions/src/functions/*.js`). Fix `main` before starting or no functions register.
+
+---
+
+## Reading host output (pass/fail)
+
+| Console signal | Meaning | Action |
+|----------------|---------|--------|
+| Each function name listed under "Functions:" | Registered | PASS |
+| `No job functions found.` | Build/`main` mismatch | Fix `main`/build, restart |
+| `ERR_MODULE_NOT_FOUND` / broken import | Bad import or missing dist | Fix import/build, restart |
+| Constructor throws on startup | A service (often Enhancement) throws in its constructor | Defer config validation out of the constructor / wrap in try-catch, restart |
+
+---
+
+## Probing endpoints
+
+| Probe | Expected | Verdict |
+|-------|----------|---------|
+| `GET /api/health` | `200` with status body | PASS (required) |
+| `GET` a list/read endpoint | `200` with array/object, or clean `401/400` | PASS |
+| A write endpoint with missing/invalid body | `400`/`401` structured error | PASS (validation working) |
+| Any endpoint returning `500` | Schema missing, service crash, unhandled error | **FAIL — investigate & fix** |
+
+A clean `4xx` (missing auth, invalid body) is a **PASS** — it proves validation and routing work. A `500` is a **FAIL**: most often a missing table (revisit Step 1) or a service constructor crash.
+
+Use `curl`/`Invoke-RestMethod` or the browser tool to hit endpoints. Stop the host when probing is done (unless Step 4 will reuse it).

.github/agents/azure-project-integrate/references/wire-live-data.md

@@ -0,0 +1,94 @@
+<!-- azure-cor-disclaimer -->
+> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.
+
+# Wire Frontend to Live Data
+
+> Read at **Step 3**. The scaffold built the frontend behind a stable `ApiClient` seam (`src/api/`), so wiring to live data is a **one-file swap** at the seam plus a types switch — not a call-site rewrite.
+
+---
+
+## The seam the scaffold left you
+
+The scaffold wired the frontend so **no page or hook imports the mock directly**. They all import a single `api` object from `services/web/src/api/`:
+
+- `src/api/types.ts` — the `ApiClient` interface (one method per endpoint in the route inventory).
+- `src/api/mockClient.ts` — the mock implementation of `ApiClient` (reads `src/mocks/data.ts`).
+- `src/api/index.ts` — the **single swap point**: `export const api: ApiClient = mockClient;`
+
+Your job is to add the live implementation and repoint that one file. Because pages/hooks import only `api` from the seam, **you do not touch them**.
+
+---
+
+## Goal: no mock data remains in use
+
+After this step, a search of the frontend `src/` for `mock` / `mockData` / `previewState` must find nothing that is still imported. The app fetches everything from the live backend.
+
+---
+
+## Replacement recipe (one-file swap)
+
+1. **Adopt shared types.** Point `src/api/types.ts` (or the local entity types it references) at the shared package instead of the duplicated local types:
+   ```ts
+   import type { PublicUser, CreateUserRequest } from '@app/shared';
+   ```
+   No `any`. The `ApiClient` interface stays the same shape — only the types it references come from the shared contract.
+2. **Build the live client** at `src/api/client.ts` — a second implementation of the **same `ApiClient` interface**, method-for-method, so it drops into the seam without touching callers:
+   ```ts
+   import type { ApiClient } from './types';
+   import type { PublicUser, CreateUserRequest } from '@app/shared';
+
+   const BASE = import.meta.env.VITE_API_BASE ?? '/api';
+
+   async function request<T>(path: string, init?: RequestInit): Promise<T> {
+     const res = await fetch(`${BASE}${path}`, {
+       headers: { 'Content-Type': 'application/json', ...(init?.headers ?? {}) },
+       ...init,
+     });
+     if (!res.ok) {
+       const body = await res.json().catch(() => ({}));
+       throw new ApiError(res.status, body?.error?.message ?? res.statusText);
+     }
+     return res.json() as Promise<T>;
+   }
+
+   export const liveClient: ApiClient = {
+     listUsers: () => request<PublicUser[]>('/users'),
+     getUser: (id) => request<PublicUser>(`/users/${id}`),
+     // ...one method per endpoint, matching the ApiClient interface exactly
+   };
+   ```
+   Because `liveClient` is typed `: ApiClient`, the compiler guarantees it covers every method the pages already call.
+3. **Swap the seam — the one file that changes.** Edit `src/api/index.ts` so `api` points at the live client:
+   ```ts
+   import type { ApiClient } from './types';
+   import { liveClient } from './client';
+   export const api: ApiClient = liveClient;
+   export type { ApiClient } from './types';
+   ```
+   That single line (`mockClient` → `liveClient`) is the entire wire-up for the call sites. **No page or hook edits.**
+4. **Remove the mock layer.** Delete `src/api/mockClient.ts` and `src/mocks/*` (and any local duplicated types now sourced from shared). A lingering `import … from './mockClient'` or `from '../mocks'` means the step is not done.
+5. **Remove the Mock State Switcher.** The scaffold always adds a dev-only state switcher (`src/api/previewState.ts` + a fixed-corner Data/Loading/Empty/Error component) that forces the mock client into `loading` / `empty` / `error`. Delete `src/api/previewState.ts`, its corner-switcher component, and every `previewState` import/usage in the mock client, pages, hooks, and app shell. Live data is the only source now — a lingering `import … previewState` or a rendered Data/Loading/Empty/Error switcher means the step is not done.
+6. **Rebuild.** `npm --prefix services/web run build` — zero errors, zero `any`. Fix any `.ts`/`.tsx` extension mismatch (JSX must be `.tsx`).
+
+> **If the scaffold did NOT leave a `src/api/` seam** (older scaffold, or a hand-written frontend): fall back to the call-site approach — find every `import … from '.../mocks'`, replace with a real `api.*` call, preserve the four data states. But first establish the seam (`src/api/index.ts`) so any future change stays a one-file swap.
+
+
+---
+
+## Dev proxy (so `/api` reaches the backend)
+
+Point the dev server's `/api` proxy at the backend host from Step 2.
+
+**Vite** (`vite.config.ts`):
+```ts
+export default defineConfig({
+  server: {
+    host: true,          // preserve preview compatibility (webview iframe / forwarded host)
+    allowedHosts: true,  // dev-only: don't 403-block the webview / forwarded origin
+    strictPort: false,
+    proxy: { '/api': { target: 'http://localhost:7071', changeOrigin: true } },
+  },
+});
+```
+
+**Keep** the `host` / `allowedHosts` / `strictPort` settings the scaffold added — they let the frontend load inside a webview iframe and forwarded (remote / Codespaces) hosts; only add the `proxy` entry. For other frameworks use their equivalent proxy config (Next.js `rewrites`, Angular `proxy.conf.json`). Keep the target in sync with the backend port the artifact documents.