──────

### 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
2026-09-20 23:33:55 +02:00
parent f935bbeb8c
commit 635a130f0b
195 changed files with 28309 additions and 957 deletions
@@ -0,0 +1,138 @@
+<!-- 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.
+
+# {Runtime} — Debug & Build Configuration
+
+> **Template** — Copy this file to `runtimes/{rt}.md` when adding a new runtime.
+
+---
+
+## Prerequisites
+
+<!-- Required tools, SDKs, version managers — language toolchain only. -->
+<!-- Do NOT list project-type-specific tools here (e.g., Functions Core Tools belongs in functions.md). -->
+
+| Tool | Detection Command | Required For | Install Link |
+|------|-------------------|-------------|-------------|
+| `{tool}` | `{tool} --version` | {purpose} | `{install-url}` |
+
+---
+
+## Debugger Properties
+
+<!-- Generic debug properties for this runtime.
+     See project-types/{type}.md § Runtime Wiring for how these combine with the host command.
+     See generate.md § Source Ownership for how runtime and project-type refs compose. -->
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Debug protocol | `{protocol}` | The wire protocol the runtime exposes (e.g., `Node Inspector`, `CoreCLR DAP`, `debugpy DAP`, `JDWP`, `Delve DAP`). |
+| VS Code debugger type | `{type}` | The VS Code debugger adapter identifier (e.g., `node`, `coreclr`, `debugpy`, `java`, `go`). |
+| Base debug port | `{port}` | Default debug port for this runtime; overridden per-service in monorepos |
+
+### VS Code Problem Matchers
+
+<!-- Problem matchers for VS Code tasks.json. -->
+
+| Task | Watch Problem Matcher | Build Problem Matcher |
+|------|----------------------|----------------------|
+| {task} | `{matcher}` | `{matcher}` |
+
+---
+
+## Build Chain
+
+<!-- Build steps owned by this runtime: install, build/watch.
+     The startup task is provided by the project type's Runtime Wiring table, not this file.
+     Wire: startup task depends on ["build/watch step", "Start Emulators"]. -->
+
+Chain shape (startup task comes from the project type):
+
+```
+"{service-id}: {startup task}"              ← from project-types/{type}.md Runtime Wiring
+       ├── dependsOn: "{service-id}: {build/watch step}"  ← this file
+       └── dependsOn: "Start Emulators"     ← only when emulators are required
+```
+
+> **Task label scoping:** All task labels MUST be prefixed with the service ID derived from the plan's Service Label column. See [generate.md § Service ID Derivation](../generate.md).
+
+### Build Commands
+
+| Step | Command | Purpose | Background? |
+|------|---------|---------|------------|
+| Start Emulators | `docker compose up -d` | Start all emulator services (idempotent — no-op if already running) | No |
+
+See [generate.md](../generate.md) § Task `runOptions` Rules for how these build steps are rendered into VS Code task configuration.
+
+---
+
+## Convenience Scripts
+
+<!-- HOW scripts are registered for this runtime (package.json, Makefile, pyproject.toml, scripts/ dir).
+     The plan's Convenience Scripts table drives WHICH scripts to generate — do not hardcode script names here. -->
+
+The plan's Convenience Scripts table specifies WHICH scripts to generate. This section covers HOW to register them for this runtime.
+
+**Script runner:** `{file}` (e.g., `package.json` scripts, `scripts/` directory, `Makefile`, `pyproject.toml`)
+**Run command pattern:** `{command}` (e.g., `npm run {script}`, `./scripts/{script}.sh`)
+
+> When the runtime's script runner is not inherently cross-platform (e.g., standalone scripts vs `package.json`), generate platform-appropriate scripts or document cross-platform alternatives.
+
+### Script Format
+
+<!-- Show the format for adding a script entry to this runtime's script runner. -->
+
+### Common Script Implementations
+
+Use these implementations when building scripts from the plan:
+
+| Script Purpose | Typical Command | Notes |
+|---------------|-----------------|-------|
+| Start emulators | `docker compose up -d` | Idempotent — safe to re-run |
+| Stop emulators | `docker compose down` | Stops and removes containers |
+| Clean emulator data | Stop containers with volumes, then remove bind-mount data directories | Run `docker compose down -v` (`-v` also drops **named volumes** like Postgres's `postgres_data`), then remove `{data-dirs}` = `./.{name}` **bind-mount** directories derived from `docker-compose.yml` `volumes:` mounts. Use platform-appropriate removal. |
+| Run migrations | `{migration tool CLI command}` | See [migrations.md](../migrations.md) for how to determine the command |
+
+---
+
+## VS Code Extension Recommendations (`.vscode/extensions.json`)
+
+<!-- Extensions required by this runtime. Aggregated with project-type extensions into .vscode/extensions.json by generate.md. -->
+
+| Extension ID | Why Required |
+|--------------|-------------|
+| `{extension-id}` | {reason} |
+
+---
+
+## VS Code Workspace Settings (`.vscode/settings.json`)
+
+<!-- Settings contributed by this runtime. Aggregated with project-type settings into .vscode/settings.json by generate.md. -->
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| `{setting.key}` | `{value}` | {reason} |
+
+---
+
+## Checklist — {Runtime} Validation
+
+> ⛔ **MANDATORY — runs during Phase 3 validation after all artifacts are generated.** You MUST verify every item below. Do NOT skip, assume, or approximate results.
+
+<!-- Post-generation self-check for this runtime. Verify generated artifacts are correct — do not run or start anything. -->
+
+After generating VS Code configuration, verify the following were produced correctly:
+
+### Post-Generation Checks
+
+1. ✅ Build task exists in `tasks.json` with the correct problem matcher
+2. ✅ `launch.json` uses the correct debugger type and request mode
+3. ✅ `.vscode/extensions.json` includes runtime extensions listed above
+
+### Live Validation Checks
+
+<!-- These checks run during Phase 3 validation (validation.md Step 7), after the ready signal is observed.
+     Add debugger-specific verifications here (e.g., process attachment, source map verification).
+     validation.md delegates to this section — if you add checks here, they WILL be executed. -->
+
+> Project-type-specific checks (e.g., startup task, connection strings) are defined in `project-types/{type}.md`.
@@ -0,0 +1,194 @@
+<!-- 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.
+
+# .NET / C# — Debug & Build Configuration
+
+> Covers **.NET** projects. Project-type-specific hosting (Functions, App Service, etc.) is defined in `project-types/{type}.md` — this file covers the .NET runtime layer only.
+
+## Prerequisites
+
+| Tool | Detection Command | Required For | Install Link |
+|------|-------------------|-------------|-------------|
+| .NET SDK | `dotnet --version` | Build and run .NET projects | [dotnet.microsoft.com](https://dotnet.microsoft.com/download) |
+| C# extension | VS Code extension `ms-dotnettools.csharp` installed | Contributes the `coreclr` debugger type required for F5 debugging | [Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) |
+
+---
+
+## Debugger Properties
+
+<!-- Generic debug properties for this runtime.
+     See project-types/{type}.md § Runtime Wiring for how these combine with the host command.
+     See generate.md § Source Ownership for how runtime and project-type refs compose. -->
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Debug protocol | `CoreCLR DAP` | .NET Core / .NET 5+ debug adapter protocol |
+| VS Code debugger type | `coreclr` | Contributed by the C# extension (`ms-dotnettools.csharp`) |
+| Request mode | `attach` | VS Code attaches to a running .NET process by `processName` |
+| Base debug port | — | CoreCLR attach uses `processName`, not a port |
+
+### VS Code Problem Matchers
+
+| Task | Watch Problem Matcher | Build Problem Matcher |
+|------|----------------------|----------------------|
+| `dotnet build` | — | `$msCompile` |
+
+---
+
+## processName Determination
+
+The `coreclr` debugger (request: `attach`) matches `processName` **literally** against the OS process list. Getting this wrong means F5 silently fails.
+
+### Cross-Platform Rules
+
+| Platform | Process name | Example |
+|----------|-------------|---------|
+| Windows | `{AssemblyName}.exe` | `Scrapbook.Api.exe` |
+| macOS / Linux | `{AssemblyName}` (no extension) | `Scrapbook.Api` |
+
+> ⛔ **Windows requires the `.exe` suffix.** Writing `"Scrapbook.Api"` instead of `"Scrapbook.Api.exe"` produces:
+>
+> ```
+> No process with the specified name is currently running.
+> ```
+
+### Deriving `AssemblyName`
+
+The process name is derived from the project's `.csproj`:
+
+1. If `<AssemblyName>` is defined, use that value
+2. Otherwise, the `.csproj` filename without extension (e.g., `Functions.csproj` → `Functions`)
+3. The `.csproj` **MUST** have `<OutputType>Exe</OutputType>` — otherwise no executable is produced and there's no target to debug
+
+**Verify before writing `launch.json`:** after `dotnet build`, confirm the executable exists at `{projectDir}/bin/Debug/{tfm}/{AssemblyName}[.exe]`.
+
+> ❌ **Do NOT use `${command:pickProcess}` or `${command:azureFunctions.pickProcess}`** — both pop a blocking dialog every F5. Use literal `processName`.
+
+---
+
+## Build Chain
+
+Tasks owned by this runtime: build. The startup task and its dependency wiring are provided by the project type's Runtime Wiring table — not this file.
+
+> **Task label scoping:** All task labels MUST be prefixed with the service ID (e.g., `functions-api: dotnet build`). See [generate.md § Service ID Derivation](../generate.md).
+
+Chain shape (startup task comes from the project type):
+
+```
+"{service-id}: {startup task}"              ← from project-types/{type}.md Runtime Wiring
+       ├── dependsOn: "{service-id}: dotnet build"   ← this file
+       └── dependsOn: "Start Emulators"     ← only when emulators are required
+```
+
+### Build Commands
+
+| Step | Task Label | Command | Purpose | Background? |
+|------|-----------|---------|---------|------------|
+| build | `{service-id}: dotnet build` | `dotnet build {path-to-csproj} --configuration Debug` | Restore + compile | No |
+
+```json
+{
+  "label": "{service-id}: dotnet build",
+  "type": "process",
+  "command": "dotnet",
+  "args": [
+    "build",
+    "${workspaceFolder}/{path-to-csproj}",
+    "--configuration",
+    "Debug"
+  ],
+  "problemMatcher": "$msCompile",
+  "group": "build",
+  "runOptions": { "instanceLimit": 1, "instancePolicy": "silent" }
+}
+```
+
+> .NET does not have a watch-based incremental compile step in the debug chain (unlike TypeScript's `tsc --watch`). Each F5 re-runs `dotnet build`.
+
+See [generate.md](../generate.md) § Task `runOptions` Rules for how these build steps are rendered into VS Code task configuration.
+
+---
+
+## Convenience Scripts
+
+The plan's Convenience Scripts table specifies WHICH scripts to generate. This section covers HOW to register them for .NET projects.
+
+Because .NET projects do not have a built-in script runner equivalent to `npm run`, convenience scripts live as standalone scripts under `scripts/`.
+
+**Script runner:** Scripts in `scripts/` directory
+**Run command pattern:** Platform-dependent (see below)
+
+### Script Format
+
+Generate scripts appropriate for the user's platform:
+
+| Platform | File extension | Shebang / header | Make executable |
+|----------|---------------|-------------------|-----------------|
+| macOS / Linux | `.sh` | `#!/bin/bash` | `chmod +x` |
+| Windows | `.ps1` | — | — (PowerShell scripts run directly) |
+
+> When the platform is ambiguous, generate `.sh` scripts — they also work on Windows via Git Bash or WSL.
+
+### Common Script Implementations
+
+Use these implementations when building scripts from the plan:
+
+| Script Purpose | Typical Command | Notes |
+|---------------|-----------------|-------|
+| Start emulators | `docker compose up -d` | Idempotent — safe to re-run |
+| Stop emulators | `docker compose down` | Stops and removes containers |
+| Clean emulator data | Stop containers with volumes, then remove bind-mount data directories | Run `docker compose down -v` (`-v` also drops **named volumes** like Postgres's `postgres_data`), then remove `{data-dirs}` = `./.{name}` **bind-mount** directories derived from `docker-compose.yml` `volumes:` mounts. Use platform-appropriate removal (e.g., `rm -rf` on macOS/Linux, `Remove-Item -Recurse` on Windows) |
+| Run migrations | `{migration tool CLI command}` | See [migrations.md](../migrations.md) for how to determine the command |
+
+---
+
+## VS Code Extension Recommendations (`.vscode/extensions.json`)
+
+<!-- Extensions required by this runtime. Aggregated with project-type extensions into .vscode/extensions.json by generate.md. -->
+
+| Extension ID | Why Required |
+|--------------|-------------|
+| `ms-dotnettools.csharp` | Contributes the `"type": "coreclr"` debugger for .NET attach/launch |
+| `ms-dotnettools.csdevkit` | C# Dev Kit — adds Solution Explorer, test discovery, and enhanced debugging experience |
+
+> Project-type-specific extensions (e.g., `ms-azuretools.vscode-azurefunctions` for Functions) are listed in `project-types/{type}.md`.
+
+---
+
+## VS Code Workspace Settings (`.vscode/settings.json`)
+
+<!-- Settings contributed by this runtime. Aggregated with project-type settings into .vscode/settings.json by generate.md. -->
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| `files.exclude: **/bin` | `true` | Hide .NET build output from explorer |
+| `files.exclude: **/obj` | `true` | Hide .NET intermediate build files from explorer |
+
+> These exclusions reduce workspace noise. They are deep-merged with any existing `files.exclude` entries — see [generate.md § VS Code Workspace Settings](../generate.md).
+
+---
+
+## Checklist — .NET Runtime Validation
+
+> ⛔ **MANDATORY — runs during Phase 3 validation after all artifacts are generated.** You MUST verify every item below. Do NOT skip, assume, or approximate results.
+
+After generating VS Code configuration, verify the following were produced correctly:
+
+### Post-Generation Checks
+
+1. ✅ `dotnet build` task exists in `tasks.json` with `$msCompile` problem matcher
+2. ✅ `processName` in `launch.json` matches the `AssemblyName` derived from `.csproj` (platform-appropriate — see § processName Determination)
+3. ✅ `launch.json` uses `"type": "coreclr"` with `"request": "attach"`
+4. ✅ `.vscode/extensions.json` includes `ms-dotnettools.csharp` and `ms-dotnettools.csdevkit`
+
+### Live Validation Checks
+
+These checks run during Phase 3 validation ([validation.md](../validation.md) Step 7), after the ready signal is observed:
+
+1. ✅ Verify the target process exists for attachment — the `processName` in `launch.json` must match a running OS process:
+   - **Windows PowerShell:** `Get-Process -Name "<processName without .exe>" -ErrorAction SilentlyContinue` → must return a process
+   - **macOS/Linux:** `pgrep -x "<processName>"` → must return a PID
+2. ✅ On Windows, confirm `processName` includes the `.exe` suffix (e.g., `"Scrapbook.Api.exe"`, NOT `"Scrapbook.Api"`)
+3. ✅ If process check fails, fix `launch.json` before marking the config ✅
+
+> If the process is not found, the F5 attach WILL fail with: `"No process with the specified name is currently running"`
@@ -0,0 +1,190 @@
+<!-- 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.
+
+# Node.js — Debug & Build Configuration
+
+> Covers both **JavaScript** and **TypeScript** projects. The debugger properties are identical; only the build chain differs.
+
+## Prerequisites
+
+| Tool | Detection Command | Required For | Install Link |
+|------|-------------------|-------------|-------------|
+| Node.js | `node --version` | All Node projects | [nodejs.org](https://nodejs.org/) |
+| npm | `npm --version` | Dependency management | (bundled with Node) |
+
+---
+
+## Debugger Properties
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Debug protocol | `Node Inspector` | V8 inspector protocol over WebSocket |
+| VS Code debugger type | `node` | Maps Node Inspector to VS Code's built-in Node debugger |
+| Base debug port | `9229` | Default Node.js inspector port |
+| Auto-restart | `true` | Re-attach after the host restarts on file changes |
+
+### `outFiles` (node-ts only — REQUIRED)
+
+For any TypeScript Node.js project, the `launch.json` attach configuration **must** include `outFiles` pointing to the compiled JavaScript output. Without it, VS Code cannot locate `.js.map` files and breakpoints set in `.ts` source files will not trigger.
+
+**Derivation:** Read the project's `tsconfig.json` to determine the output directory:
+1. Check `compilerOptions.outDir` — this is the compiled output root (e.g., `"outDir": "./dist"`)
+2. Construct the glob: `${workspaceFolder}/{service-root}/{outDir}/**/*.js`
+3. If `outDir` is not set, fall back to the project root: `${workspaceFolder}/{service-root}/**/*.js`
+
+> `{service-root}` is the path from the workspace root to the project directory. In a single-project workspace this is empty (just `${workspaceFolder}/dist/**/*.js`). In a monorepo it includes the nested path (e.g., `${workspaceFolder}/services/functions/dist/**/*.js`).
+
+**Example:**
+```json
+{
+  "name": "My API (debug)",
+  "type": "node",
+  "request": "attach",
+  "port": 9229,
+  "restart": true,
+  "outFiles": ["${workspaceFolder}/services/functions/dist/**/*.js"],
+  "preLaunchTask": "{service-id}: func host start"
+}
+```
+
+> `preLaunchTask` uses the canonical `{service-id}:`-prefixed task label — see [generate.md § Service ID Derivation](../generate.md). The example above corresponds to a `functions-api` service, so the resolved value is `functions-api: func host start`.
+
+> **Verify:** `tsconfig.json` must have `"sourceMap": true` in `compilerOptions` for any TypeScript project that will be debugged. Without source maps, VS Code breakpoints in `.ts` files cannot bind to the compiled `.js` output and will appear as gray (unverified) dots — even when the debugger is successfully attached. The build/watch task must run **before** the startup task so compiled output exists when the debugger attaches.
+
+### VS Code Problem Matchers
+
+| Variant | Watch Problem Matcher | Build Problem Matcher |
+|---------|----------------------|----------------------|
+| node-ts | `$tsc-watch` | `$tsc` |
+| node-js | — | — |
+
+> **Monorepo / multi-service:** When multiple Node services are present, each is assigned a sequential debug port starting from the base port defined in the project type's Runtime Wiring table. See [multi-service.md](../multi-service.md) for port assignment rules.
+
+---
+
+## Variant Detection
+
+| Signal | Variant | Notes |
+|--------|---------|-------|
+| `tsconfig.json` present | **node-ts** | TypeScript — requires compile step |
+| `package.json` without `tsconfig.json` | **node-js** | Plain JavaScript — no compile step |
+
+---
+
+## Build Chain
+
+Tasks owned by this runtime: install, clean, build, watch. The startup task and its dependency wiring are provided by the project type's Runtime Wiring table — not this file.
+
+> **Task label scoping:** All task labels MUST be prefixed with the service ID (e.g., `functions-api: npm watch`). See [generate.md § Service ID Derivation](../generate.md).
+
+### Build Commands
+
+#### node-ts (TypeScript)
+
+```
+"{service-id}: {startup task}"              ← from project-types/{type}.md Runtime Wiring
+       ├── dependsOn: "{service-id}: npm watch"
+       │                └── dependsOn: "{service-id}: npm clean"
+       │                               └── dependsOn: "{service-id}: npm install"
+       └── dependsOn: "Start Emulators"     ← only when emulators are required
+```
+
+| Step | Task Label | Command | Purpose | Background? |
+|------|-----------|---------|---------|------------|
+| install | `{service-id}: npm install` | `npm install` | Installs dependencies | No |
+| clean | `{service-id}: npm clean` | `npm run clean` | Cleans build output | No |
+| watch | `{service-id}: npm watch` | `npm run watch` | Runs `tsc --watch` for incremental builds | ✅ Yes |
+| build | `{service-id}: npm build` | `npm run build` | One-shot build (used outside debug flow) | No |
+
+#### node-js (JavaScript)
+
+```
+"{service-id}: {startup task}"              ← from project-types/{type}.md Runtime Wiring
+       ├── dependsOn: "{service-id}: npm install"
+       └── dependsOn: "Start Emulators"     ← only when emulators are required
+```
+
+| Step | Task Label | Command | Purpose | Background? |
+|------|-----------|---------|---------|------------|
+| install | `{service-id}: npm install` | `npm install` | Installs dependencies | No |
+
+> No compile, clean, or watch step — JavaScript runs directly.
+
+> **Monorepo / alternative package managers:** Adjust commands if the project uses `yarn`, `pnpm`, or a monorepo layout. The key invariant is the chain shape: **install → [clean → build/watch →] startup task** (compile steps only for TypeScript).
+
+See [generate.md](../generate.md) § Task `runOptions` Rules for how these build steps are rendered into VS Code task configuration.
+
+
+---
+
+## Convenience Scripts
+
+The plan's Convenience Scripts table specifies WHICH scripts to generate. This section covers HOW to register them for Node.js projects.
+
+**Script runner:** `package.json` `"scripts"` block
+**Run command pattern:** `npm run {script-name}`
+
+### Script Format
+
+Each script is a shell command added to `package.json` `"scripts"`. Example entry:
+
+```json
+{
+  "{script-name}": "{shell command}"
+}
+```
+
+### Common Script Implementations
+
+Use these implementations when building scripts from the plan:
+
+| Script Purpose | Typical Command | Notes |
+|---------------|-----------------|-------|
+| Start emulators | `docker compose up -d` | Idempotent — safe to re-run |
+| Stop emulators | `docker compose down` | Stops and removes containers |
+| Clean emulator data | `docker compose down -v && rimraf {data-dirs}` | `-v` (`--volumes`) also removes **named volumes** (e.g. Postgres's `postgres_data`). `{data-dirs}` = space-separated `./.{name}` **bind-mount** directories derived from `docker-compose.yml` `volumes:` mounts (e.g., `.azurite`). Use `rimraf` for cross-platform compatibility. Requires `rimraf` in `devDependencies` — see [generate.md § Dependency Availability](../generate.md). |
+| Run migrations | `{migration tool CLI command}` | See [migrations.md](../migrations.md) for how to determine the command |
+
+---
+
+## VS Code Extension Recommendations (`.vscode/extensions.json`)
+
+No recommended extensions.
+
+---
+
+## VS Code Workspace Settings (`.vscode/settings.json`)
+
+<!-- Settings contributed by this runtime. Aggregated with project-type settings into .vscode/settings.json by generate.md. -->
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| `files.exclude: **/node_modules` | `true` | Hide dependency tree from explorer — large and noisy |
+
+> This exclusion reduces workspace noise. It is deep-merged with any existing `files.exclude` entries — see [generate.md § VS Code Workspace Settings](../generate.md).
+
+---
+
+## Checklist — Node.js Runtime Validation
+
+> ⛔ **MANDATORY — runs during Phase 3 validation after all artifacts are generated.** You MUST verify every item below. Do NOT skip, assume, or approximate results.
+
+After generating VS Code configuration, verify the following were produced correctly:
+
+### Post-Generation Checks
+
+1. ✅ `launch.json` uses `"type": "node"` with the correct debug port
+2. ✅ For TypeScript: `launch.json` includes `"outFiles"` derived from `tsconfig.json` `outDir` (e.g., `["${workspaceFolder}/{service-root}/{outDir}/**/*.js"]`)
+3. ✅ For TypeScript: `tsconfig.json` has `"sourceMap": true` — without it, breakpoints in `.ts` files appear as gray (unverified) dots
+4. ✅ For TypeScript: watch task exists in `tasks.json` with `$tsc-watch` problem matcher
+5. ✅ For TypeScript: build chain follows install → clean → watch dependency order
+
+### Live Validation Checks
+
+These checks run during Phase 3 validation ([validation.md](../validation.md) Step 7), after the ready signal is observed:
+
+1. ✅ For TypeScript: verify `tsconfig.json` has `"sourceMap": true` in `compilerOptions`. If missing, add `"sourceMap": true` and re-run the build task before marking the config ✅
+
+> The Node Inspector debug port (`9229`) is handled automatically by the Functions host or `--inspect` flag.
+
+> Project-type-specific checks (e.g., `{service-id}: func host start` task, connection strings) are defined in `project-types/{type}.md`.