──────

### 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,4 @@
+{
+    "name": "azure-debug-plan",
+    "version": "0.0.1"
+}
@@ -0,0 +1,68 @@
+<!-- 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.
+
+# Azure Debug Plan
+
+> **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE**
+>
+> This document is the **official, canonical source** for classifying a workspace
+> and generating a VS Code debug setup plan. You **MUST** follow these instructions
+> exactly as written. When in doubt, defer to this document. Do not improvise,
+> infer, or substitute steps.
+
+---
+
+## Global Rules (NO EXCEPTIONS)
+
+1. **Update plan progressively** — Mark steps complete as you go; update **Last Updated** timestamp on every status change
+2. ❌ **Destructive actions require `ask_user`** — Always confirm before overwriting, deleting, or modifying existing files
+3. **Preserve existing config** — Never silently overwrite project configuration files or `docker-compose.yml`. Merge or ask first.
+4. **Scope — VS Code debug setup only** — This instruction set classifies the workspace and generates a plan. Cloud architecture, IaC generation, provisioning, and deployment are handled by the **azure-deploy** agent through the complete **azure-app-onboard** pipeline.
+---
+
+## Autopilot mode (overrides the approval STOP)
+**Active when** the invoking chat query begins with `[AUTOPILOT MODE]`, **or** `.azure/project-plan.md` records `executionMode: auto` or equivalent. When active, run fully unattended:
+- **Phase 0–1 still run in full**.  When generating the plan `.azure/vscode-debug-plan.md`, also record `executionMode: auto` or similar.  Follow any specific instructions per the template.
+- Skip the step that instructs to run `openLocalPlanView` and do NOT wait for approval. Set status straight to `Approved`, then invoke `azure-debug-generate` as you normally would, but with the chat arg prefixed with `[AUTOPILOT MODE] `.
+- **Reuse the project-plan prerequisites.** When `.azure/project-plan.md` already lists Prerequisites, carry them over wholesale instead of re-deriving them — see [inventory.md § Step 1](references/inventory.md) for the detail.
+- Never call `ask_user` for non-destructive steps. Scan completeness is unchanged — autopilot suppresses **the preview and approval gates only**.
+
+## Workflow
+
+> **Two phases — Classify → Plan — then STOP.**
+>
+> Do NOT generate any configuration files (docker-compose, launch.json, tasks.json, etc.).
+> All `.azure/` artifacts must be created inside the **workspace root**, not a session-state folder.
+
+---
+
+## Phase 0: Classify
+
+Scan the workspace for service roots. Produce a `services[]` list.
+
+| Action | Reference |
+|--------|-----------|
+| Check for `.azure/project-plan.md` — if found, read it for advisory context. | — |
+| Scan all subdirectories; detect project type + runtime per service root | [classify.md](references/classify.md) |
+| If 2+ service roots: assign service IDs, deduplicate emulators, plan compound debug config | [multi-service.md](references/multi-service.md) |
+
+---
+
+## Phase 1: Plan
+
+Scan dependencies, detect configuration, and generate the plan directly. The user reviews and edits the plan markdown before approving.
+
+| # | Action | Reference |
+|---|--------|-----------|
+| 1 | **Detect prerequisites** — Check required tools and VS Code extensions | [inventory.md](references/inventory.md) § Step 1 |
+| 2 | **Scan Azure dependencies** — For each service, scan bindings (Functions) or SDK packages (other types) to identify Azure service dependencies | [inventory.md](references/inventory.md) § Step 2 |
+| 3 | **Map dependencies to emulators** — Map each detected Azure dependency to its local emulator. Deduplicate across services. | [inventory.md](references/inventory.md) § Step 2 |
+| 4 | **Detect container runtime & Compose provider** — Scan for an existing `docker-compose.yml`/`compose.yaml` and detect the available container runtime per [prerequisites.md § Container runtime detection](../../shared-references/prerequisites.md). Record the chosen runtime (**Docker**, **Podman**, or **Podman (Docker-compatible)**) and its Compose command in the plan's Orchestrator table. **Prefer the Podman engine when it's ready** — native `podman compose`, or `docker compose` when the Docker CLI is backed by Podman; fall back to Docker, and default to Docker Compose only when neither is confirmed. | [prerequisites.md](../../shared-references/prerequisites.md) |
+| 5 | **Detect migrations** — Scan for migration files, dependencies, and scripts | [migrations.md](references/migrations.md) |
+| 6 | **Inventory API test opportunities** — List HTTP endpoints and triggers per service | [inventory.md](references/inventory.md) § Step 3 |
+| 7 | **Write plan** — Generate `.azure/vscode-debug-plan.md` from scan results. Fill all sections completely. | [plan-template.md](references/plan-template.md) |
+| 8 | **Present plan** — Show plan to user and ask for approval. Highlight any ❓ prerequisites to double-check. The user can edit the plan directly before approving. On approval, update status to `Approved`. | `.azure/vscode-debug-plan.md` |
+
+---
+
+> **❌ STOP HERE** — Do NOT proceed to artifact generation. Do NOT generate docker-compose.yml, launch.json, tasks.json, or any other configuration files. Present the plan to the user and wait for approval. After approval, the custom agent wrapper will invoke `azure-debug-generate` to handle generation.
@@ -0,0 +1,33 @@
+<!-- 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.
+
+# Classify Workspace
+
+Determine the project type(s) and runtime(s) for each service root in the workspace. Classification produces an array of service contexts — even single-service workspaces produce a one-item list so the rest of the flow is uniform.
+
+> **Always scan the full directory tree** — not just the workspace root. Service roots nested in subdirectories (e.g. `./api/`, `./web/`) must be found regardless of project layout.
+> Ignore: `node_modules/`, `.git/`, `dist/`, `build/`, `bin/`, `obj/`.
+
+### ⚠️ Exclude Non-Service Directories
+
+Only include directories that represent **runnable services** (APIs, web apps, functions, workers, etc.). Exclude directories that are **shared libraries, utility packages, or common modules** — these are consumed by services but are not independently launchable and should never appear as a service.
+
+Common exclusion signals:
+- Directory name or `package.json` name contains `shared`, `common`, `utils`, `lib`, or `helpers`
+- No entry point (no `main`, `start` script, `host.json`, `server.*`, or framework config)
+- Used as a dependency by other service roots (e.g. via workspace references or `file:` dependencies)
+- Project type is `library` — a package that exports modules but is not runnable on its own
+
+---
+
+## Step 1: Detect Project Types
+
+Scan every subdirectory and classify each service root by project type. See [project-types.md](project-types.md) for the detection table and per-type nuances.
+
+## Step 2: Detect Runtimes
+
+For each service root, determine the language/runtime and version. See [runtimes.md](runtimes.md) for the detection table and per-runtime nuances.
+
+## Output
+
+Classification produces a `services[]` list of `{ root, projectType, runtime, ... }` entries. Even single-service workspaces produce a one-item list. This information will be used in follow-up sections.
@@ -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.
+
+# Inventory
+
+Scan the workspace to populate the plan. For multi-service workspaces, loop over each service in `services[]` from classify.md; deduplicate emulators across services per [multi-service.md](multi-service.md).
+
+---
+
+## Step 1: Prerequisites
+
+### Autopilot: Reuse the Project Plan Prerequisites
+
+**Autopilot mode only.** In autopilot, if `.azure/project-plan.md` exists and lists Prerequisites (its `### Run` and `### Debug` groups), carry those prerequisites over wholesale into the debug plan instead of re-deriving them — the planning stage already inventoried them, and autopilot has no approval gate to catch a dropped prerequisite. Add any prerequisites the workspace scan reveals that project-plan is missing, and don't silently override a project-plan entry. Only when project-plan has no Prerequisites do you fall back to deriving them from the workspace scan below.
+
+In interactive (non-autopilot) mode, derive prerequisites from the workspace scan as usual; the user reviews and edits the plan before approving.
+
+### Deriving Prerequisites from the Workspace Scan
+
+Identify required tools and then inventory them by following [prerequisites.md](../../shared-references/prerequisites.md).
+
+The required tools are derived from a scan of the currently opened workspace project — check only the tools and extensions relevant to the detected project types, runtimes, and Azure bindings. Both tool sets defined in prerequisites.md apply here — the **Run** tools (Node.js, .NET SDK, Python, Functions Core Tools, ...) and the **Debug** tools (Docker, Docker Compose, VS Code extensions, ...) — since debugging exercises the full local stack.
+
+For every detected project type, include its VS Code debug-integration extension from the Debug Tools table as its own Debug row (e.g. an Azure Functions project always includes `ms-azuretools.vscode-azurefunctions`) — these extensions are required for the debug experience and are separate from the Run-group CLI/runtime tools, so never omit them.
+
+---
+
+## Step 2: Azure Dependencies
+
+For each service, identify Azure service dependencies by scanning bindings or SDK packages.
+
+- **Functions projects:** Scan bindings per [project-types.md](project-types.md) § functions
+- **Other project types:** Scan dependency files (e.g. `package.json`, `requirements.txt`, `*.csproj`) for packages that indicate an Azure service dependency
+
+The table below shows common SDK-to-service mappings — this is **not exhaustive**. Any package that implies connectivity to an Azure service should be mapped accordingly.
+
+| Example Packages | Azure Service | Emulator |
+|-----------------|--------------|----------|
+| `@azure/storage-blob`, `@azure/storage-queue`, `@azure/data-tables` | Azure Storage | azurite |
+| `pg`, `postgres`, `@prisma/client`, `typeorm`, `sequelize`, `Npgsql`, `psycopg2` | PostgreSQL | postgresql |
+| `@azure/cosmos` | Cosmos DB | cosmosdb-emulator |
+| `@azure/service-bus` | Service Bus | servicebus-emulator |
+| `@azure/event-hubs` | Event Hubs | eventhubs-emulator |
+| `mssql`, `Microsoft.Data.SqlClient` | Azure SQL | azure-sql-edge |
+
+> Multiple storage bindings (blob + queue + table) consolidate to a **single** azurite entry.
+> Cross-check `local.settings.json`, `.env`, and app config for existing connection references to confirm findings.
+
+---
+
+## Step 3: API Test Collection Inventory
+
+For each service, identify whether it exposes testable HTTP endpoints or triggers and provide a brief summary for the plan. Inventory the implemented route and trigger registrations in the workspace, not only the route table in `.azure/project-plan.md`. The project plan intentionally omits derived authentication routes, so include implemented registration, login, and current-user endpoints when `API Login` is enabled. Detailed endpoint parsing happens during the generation phase.
@@ -0,0 +1,47 @@
+<!-- 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.
+
+# Database Migrations — Detection
+
+When a database dependency is found, detect the migration tool so the plan can record it. The generation phase uses this to configure migration automation within the orchestrator.
+
+---
+
+## Detection
+
+Scan three layers, then synthesize.
+
+### Layer 1: Migration Files
+
+Non-exhaustive detection pattern examples:
+
+| Pattern | Tool |
+|---------|------|
+| `prisma/migrations/` | Prisma |
+| `alembic/`, `alembic.ini` | Alembic |
+| `**/migrations/*.py` | Django |
+| `Migrations/*.cs` | EF Core |
+| `flyway.conf` | Flyway |
+| `migrations/*.sql` | Raw SQL |
+
+### Layer 2: Dependencies
+
+Check dependency manifests for migration tools, ORMs with built-in migration support, and database driver packages.
+
+### Layer 3: Scripts
+
+Check script runners (`package.json`, `Makefile`, etc.) for existing migration commands (grep for common migration key words like: `migrate`, `schema`, `seed`).
+
+### Synthesis
+
+1. Cross-reference all three layers — they should agree
+2. If an existing migration command exists, use it (don't invent a new one)
+3. If layers conflict, ask the user which tool is active
+
+### Insufficient Evidence
+
+If a database dependency exists but no migration strategy is found across all three layers:
+
+1. Do not guess
+2. Ask the user via `ask_user` how they manage schema changes
+3. Record the gap in the plan's Migrations section with `⚠️ Not detected`
@@ -0,0 +1,48 @@
+<!-- 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.
+
+# Multi-Service Orchestration
+
+> Runs when `classify.md` finds **2+ service roots**, before inventory scanning begins.
+
+---
+
+## Service ID Assignment
+
+Derive a short kebab-case ID per service root. Use project manifest name if available, otherwise fall back to directory name.
+
+| Runtime | Manifest Source | Field |
+|---------|----------------|-------|
+| `node-ts`, `node-js` | `package.json` | `"name"` |
+| `dotnet` | `*.csproj` | `<AssemblyName>` or filename |
+| *Other* | Service directory name | Fallback when no manifest name exists |
+
+If two IDs collide, append the project type (e.g. `payments-api` becomes `payments-api-functions`).
+
+---
+
+## Emulator Deduplication
+
+Collect emulator lists from all services. Each emulator appears **once** in the plan's Emulators table — multiple services may depend on the same emulator.
+
+---
+
+## Partial Configuration
+
+Check each service root for existing debug config before planning.
+
+| State | Plan Action |
+|-------|------------|
+| Fully configured | Skip |
+| Partially configured | Generate only missing artifacts |
+| Unconfigured | Full generation |
+
+---
+
+## Compound Debug Configuration
+
+Required when 2+ service roots are detected (including Frontend SPAs).
+
+### Startup Dependencies
+
+If a frontend SPA has a proxy pointing to a local backend (detected via [project-types.md](project-types.md) § Backend Proxy Dependencies), record the `proxyTarget` service ID on that service entry. The compound config uses this to order startup (backends before frontends) that depend on them.
@@ -0,0 +1,222 @@
+<!-- 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.
+
+# Plan Template
+
+> Generate `.azure/vscode-debug-plan.md` using this template. This file is the
+> **single source of truth** for the generation phase. The generation phase reads this plan and
+> generates all artifacts from it — no re-scanning of the workspace is needed.
+>
+> The plan is generated directly from the workspace scan. The user reviews the plan,
+> edits it as needed, then approves it before generation proceeds.
+
+## ⛔ BLOCKING REQUIREMENT
+
+You **MUST** create this plan file and get user approval BEFORE generating any configuration files.
+
+---
+
+## Markdown Table Integrity
+
+When editing markdown tables with `replace_string_in_file` or `multi_replace_string_in_file`, always **read the file back** after the edit and verify that each table row is on its own line. Markdown tables require exactly one row per line — a missing newline between `|---|` and `| data |` breaks parsing completely.
+
+**Post-edit verification rule:** After any edit to `.azure/vscode-debug-plan.md` that modifies a table, immediately read the affected lines back to confirm the table renders correctly (header, separator, and each data row on separate lines). If rows are concatenated, fix before proceeding.
+
+---
+
+## ⚠️ Mermaid Label Quoting — ALWAYS Quote Every Label
+
+In the `## Architecture Diagram` mermaid block, **every node label and every edge label MUST be wrapped in double quotes.** This rule is unconditional — quote every label, every time, even when it looks harmless.
+
+```mermaid
+graph LR
+    %% ✅ CORRECT — every label quoted
+    API["Commerce API<br/>Azure Functions :7071"] -->|"@azure/storage-blob"| AZ["Azurite<br/>:10000"]
+    API -->|"pg"| PG[("PostgreSQL<br/>:5432")]
+
+    %% ❌ WRONG — unquoted labels; the leading @ is a parse error
+    %% API[Commerce API<br/>Azure Functions :7071] -->|@azure/storage-blob| AZ[Azurite]
+```
+
+**Why:** mermaid v11 uses `@` for edge-ID (`e1@-->`) and node-metadata (`id@{ shape: ... }`) syntax, so an `@` at the **start** of an unquoted label is lexed as a link ID and the whole diagram fails to parse with `Expecting 'AMP', 'COLON', ... got 'LINK_ID'`. Scoped npm package names (`@azure/storage-blob`, `@azure/identity`, `@prisma/client`) are the most common trigger, and they are exactly what shows up in Azure dependency edge labels. The debug-plan webview renders this block with mermaid — a parse error replaces the diagram with a raw `mermaid (error)` code block.
+
+Quoting is always valid in mermaid and also protects labels containing `(`, `)`, `:`, `-`, `/`, `#`, or `·`. Do **not** try to detect which labels are "risky" — just quote all of them.
+
+---
+
+## Template
+
+````markdown
+# Azure Debug Plan
+
+> This plan is the source of truth for generating the
+> VS Code debug setup in this workspace.
+>
+> **Status:** {Planning | Approved | Executing | Implemented}
+> **Execution Mode:** {Auto | Guided}
+> **Created:** {ISO-8601 datetime}
+> **Last Updated:** {ISO-8601 datetime}
+>
+> <!-- Guided Mode (default) - hand-holds the user through review and approval before generating. -->
+> <!-- Auto Mode (aka YOLO mode) — skips approval gates and runs generation unattended. -->
+
+---
+
+## Prerequisites
+
+<!-- All required tools and VS Code extensions with install status — list both the Run and Debug tool sets defined in prerequisites.md. -->
+<!-- Service(s): the service(s) that need the tool (e.g. `api`, `worker`); use `*` for global toolchain shared by all services. -->
+<!-- Installed/Version come from the detection pass and must be re-run whenever the whole plan is (re)generated or the tool set changes — never leave a placeholder. Installed is only ✅ (found) or ❓ (couldn't confirm). ❓ is informational — it just prompts the user to double-check the tool is installed. -->
+<!-- Do NOT add an Install column or any install links/URLs. The plan webview appends an Install link deterministically from a built-in catalog keyed on the tool name; links authored here are ignored. -->
+
+| Tool / Extension | Category | Service(s) | Installed | Version |
+|------------------|----------|------------|-----------|---------|
+| {name} | {Runtime / Package manager / …} | {service(s) or *} | {✅/❓} | {version or —} |
+
+> ⚠️ **Action required:** Confirm any tool or extension marked ❓ is installed and ready before approving this plan — rerun the recheck to confirm CLI tools provided by a version manager.
+
+---
+
+## Debug Configurations
+
+<!-- One row per detected service root. Each row maps to a VS Code debug configuration in launch.json. -->
+<!-- The generation phase loads project-types.md and runtimes.md based on these values. -->
+<!-- Services with Generate = No are excluded from all generation but shown for reference. -->
+<!-- Azure Dependencies drive emulator matching — see Emulators section. -->
+<!-- Debug Config Name is the VS Code debug configuration display name shown in the Run & Debug dropdown. -->
+<!-- For multi-service workspaces, include a compound debug config row at the end. -->
+<!-- ✏️ User can edit: Generate (check/uncheck), Debug Config Name -->
+
+Each checked row below produces a VS Code debug configuration in the `.vscode/launch.json`.
+
+| Generate | Debug Config Name | Service Label | Service Root | Project Type | Runtime | Version | Azure Dependencies |
+|----------|--------------------|---------------|--------------|--------------|---------|---------|-----|
+| {[x] / [ ]} | {e.g. Payments API (debug)} | {label} | {path} | {type} | {runtime} | {version} | {comma-separated azure service labels} |
+
+<!-- Example: -->
+<!-- | [x] | Payments API (debug) | Payments API | ./api | functions | node-ts | 20.x | Azure Storage, Azure PostgreSQL | -->
+<!-- | [x] | Customer Portal (debug) | Customer Portal | ./web | frontend-spa | node-ts | 20.x | — | -->
+<!-- | [x] | Debug All Services | Debug All Services | | *Compound Config* |||| -->
+
+<!-- Project Type descriptions are shown in a collapsible block so the table stays compact. -->
+<!-- Only include project types that appear in the table above. -->
+
+<details>
+<summary>ℹ️ Project Type Descriptions</summary>
+
+| Project Type | Description |
+|-------------|-------------|
+| {type} | {brief description of what this project type means} |
+
+<!-- Example: -->
+<!-- | functions | Azure Functions — serverless compute with triggers and bindings | -->
+<!-- | frontend-spa | Single-page application served by a dev server (Vite, Next.js, Angular, etc.) | -->
+<!-- | app-service | HTTP server application (Express, Fastify, Flask, ASP.NET, Spring Boot, etc.) | -->
+<!-- | container-app | Containerized application running via Dockerfile | -->
+
+</details>
+
+<!-- If a frontend SPA has a proxy config pointing to a local backend, add a note: -->
+<!-- > ℹ️ **Proxy detected:** Customer Portal proxies requests to Payments API (via `vite.config.ts`). The compound config should start backends before frontends. -->
+
+---
+
+## Orchestrator
+
+<!-- Records the container runtime and Compose provider used to run the emulator containers. -->
+<!-- Container Runtime is Docker, Podman, or "Podman (Docker-compatible)"; Compose Command is the CLI the generation phase writes into every emulator task (`docker compose` or `podman compose`). -->
+<!-- Detected from the workspace (e.g. an existing docker-compose.yml) and the container-runtime detection pass in prerequisites.md. -->
+<!-- Prefer the Podman engine when it's detected as ready (native Podman, else Podman via Docker's socket), even if Docker is too; otherwise Docker. If no runtime is detected, default to Docker Compose (Docker). The generated compose file is identical for every case. -->
+<!-- Docker-compatibility mode: when `docker`/`docker compose` is backed by the Podman engine, record Container Runtime = "Podman (Docker-compatible)" but keep Compose Command = `docker compose` — that's the command that talks to the Docker-compatible socket. -->
+<!-- ✏️ User can edit: Container Runtime / Compose Command (to switch engines, e.g. Docker → Podman) -->
+
+| Orchestrator | Container Runtime | Compose Command | Description |
+|-------------|-------------------|-----------------|-------------|
+| {Docker Compose / Podman Compose} | {Docker / Podman / Podman (Docker-compatible)} | {`docker compose` / `podman compose`} | {description} |
+
+<!-- Example (native Podman, preferred when ready): -->
+<!-- | Podman Compose | Podman | `podman compose` | Uses Podman (rootless) with `podman compose` to orchestrate emulators; the compose file is unchanged from Docker | -->
+<!-- Example (Podman via Docker's socket — engine is Podman, command stays docker compose): -->
+<!-- | Docker Compose | Podman (Docker-compatible) | `docker compose` | Runs the Podman engine through its Docker-compatible socket; `docker compose` drives Podman, compose file unchanged | -->
+<!-- Example (Docker, the fallback): -->
+<!-- | Docker Compose | Docker | `docker compose` | Uses Docker Compose to orchestrate emulators and dependent services during local development | -->
+
+---
+
+## Emulators
+
+<!-- One row per deduplicated emulator. Dependent Service is the Azure service this emulator replaces. -->
+
+| Dependent Service | Emulator | Purpose |
+|-------------------|----------|---------|
+| {azure service label} | {emulator name} | {description of what this emulator provides} |
+
+<!-- Example: -->
+<!-- | Azure Storage | Azurite Container | Blob and queue storage for photo uploads and background processing | -->
+<!-- | PostgreSQL | PostgreSQL Container | Relational database for user accounts, couples, and photo metadata | -->
+
+---
+
+## Architecture Diagram
+
+{One sentence describing how the app connects to its dependencies during debugging.}
+
+```mermaid
+graph LR
+    %% Generated from Debug Configurations + Emulators tables above.
+    %% Show each service as a node, each emulator as a node,
+    %% and edges for the Azure Dependencies that connect them.
+    %% MANDATORY: wrap EVERY node label and EVERY edge label in double quotes —
+    %% e.g. API["Commerce API<br/>Azure Functions :7071"] -->|"@azure/storage-blob"| AZ["Azurite"]
+    %% An unquoted leading @ (scoped npm packages) is parsed as mermaid edge-ID
+    %% syntax and breaks the whole diagram. See "Mermaid Label Quoting" above.
+```
+
+---
+
+## Migrations
+
+<!-- Only include this section when database migrations are detected for one or more services. Omit entirely if not applicable. -->
+<!-- ✏️ User can edit: Generate (check/uncheck) -->
+
+When selected, the generation phase creates automated VS Code tasks that run migration scripts on launch — so emulator databases are automatically provisioned with the correct schema and seed data before the app starts debugging. No manual migration steps needed.
+
+| Generate | Service | Migration Tool |
+|----------|---------|---------------|
+| {[x] / [ ]} | {service label} | {tool name, e.g. Prisma / Knex / Drizzle / EF Core} |
+
+---
+
+## API Test Collections
+
+<!-- Only include this section when one or more services expose testable HTTP endpoints or triggers. Omit entirely if not applicable. -->
+<!-- ✏️ User can edit: Generate (check/uncheck) -->
+
+When selected, the generation phase produces lightweight, runnable API test scripts in the project so you can quickly smoke-test endpoints and triggers once everything is launched and connected locally.
+
+| Generate | Service | Description |
+|----------|---------|-------------|
+| {[x] / [ ]} | {service label} | {collapsible lists of HTTP endpoints and/or triggers — see format below} |
+
+<!-- Description cell format: use collapsible <details> blocks (collapsed by default) to keep the table compact. -->
+<!-- Include an HTTP Endpoints section and/or a Triggers section as applicable. Each route/trigger on its own line. -->
+
+<!-- Example: -->
+<!-- | [x] | Functions API | <details><summary>HTTP Endpoints (16)</summary><br>GET /api/health<br>POST /api/auth/register<br>POST /api/auth/login<br>POST /api/auth/logout<br>GET /api/auth/me<br>GET /api/couples<br>POST /api/couples<br>GET /api/photos<br>POST /api/photos<br>DELETE /api/photos/:id<br>GET /api/albums<br>POST /api/albums<br>PUT /api/albums/:id<br>DELETE /api/albums/:id<br>GET /api/tags<br>POST /api/tags<br><br></details><details><summary>Triggers (2)</summary><br>blobTrigger — uploads<br>timerTrigger — cleanup</details> | -->
+
+---
+
+## Convenience Scripts
+
+<!-- The generation phase generates only checked scripts into the project's script runner. -->
+<!-- ✏️ User can edit: Generate (check/uncheck) -->
+
+| Generate | Script | Registered In | Description |
+|----------|--------|---------------|-------------|
+| {[x] / [ ]} | {script name} | {path to file where script is registered, e.g. ./package.json} | {what the script does} |
+
+<!-- Example: -->
+<!-- | [x] | emulators:start | ./package.json | Start all emulators in the background, preserving existing data | -->
+<!-- | [x] | emulators:stop | ./package.json | Stop all running emulators | -->
+<!-- | [x] | emulators:clean | ./package.json | Stop emulators and delete all data (fresh start) | -->
+<!-- | [x] | db:migrate | ./package.json | Apply pending database migrations to the emulator database | -->
@@ -0,0 +1,71 @@
+<!-- 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.
+
+# Project Types
+
+> These are **common examples, not an exhaustive list**. If a service root does not match
+> any of these, classify it by whatever best describes its purpose (e.g. `background-worker`, `console`, etc.).
+
+## Detection Table
+
+| Detection Signals | Project Type | Include in Plan? |
+|-------------------|-------------|------------------|
+| `host.json` + Azure Functions SDK | **functions** | ✅ Yes |
+| SPA framework in `package.json`, or `vite.config.*` / `next.config.*` / `angular.json` (no `host.json`) | **frontend-spa** | ✅ Yes |
+| HTTP framework (Express, Fastify, Flask, FastAPI, ASP.NET, Spring Boot, etc.) | **app-service** | ✅ Yes |
+| `Dockerfile` with a containerized application | **container-app** | ✅ Yes |
+| No entry point, no framework, exports modules only (shared/common/util packages) | **library** | ❌ Exclude |
+
+---
+
+## functions
+
+For Azure Functions projects, scan bindings to identify Azure service dependencies. Parse `function.json` files or decorator/attribute bindings in source code.
+
+> **Implicit dependency:** All Azure Functions projects require Azure Storage for the host runtime (trigger management, lease coordination, internal state). Always emit an Azurite emulator entry in the plan regardless of whether application-level storage SDK packages are detected.
+
+| Binding | Azure Service | Emulator |
+|---------|--------------|----------|
+| `blobTrigger`, `blob` | Blob Storage | azurite |
+| `queueTrigger`, `queue` | Queue Storage | azurite |
+| `table` | Table Storage | azurite |
+| `httpTrigger` | (built-in) | — |
+| `timerTrigger` | (built-in) | — |
+| `warmupTrigger` | (built-in) | — |
+| `durableClient`, `orchestrationTrigger`, `activityTrigger` | Durable Functions | durable-task-scheduler |
+| `cosmosDBTrigger`, `cosmosDB` | Cosmos DB | cosmosdb-emulator |
+| `serviceBusTrigger`, `serviceBus` | Service Bus | servicebus-emulator |
+| `eventHubTrigger`, `eventHub` | Event Hubs | eventhubs-emulator |
+| `eventGridTrigger`, `eventGrid` | Event Grid | — |
+| `signalRTrigger`, `signalR` | SignalR Service | — |
+| `sql`, `sqlTrigger` | Azure SQL | azure-sql-edge |
+
+> Multiple storage bindings (blob + queue + table) consolidate to a **single** azurite entry.
+> This table is **not exhaustive** — map any other bindings to their Azure service accordingly.
+
+---
+
+## frontend-spa
+
+Frontend SPA projects do not require emulators or Azure bindings, but they **are** service roots. When a frontend is detected alongside a backend, the workspace is multi-service and **must** produce a compound debug configuration.
+
+### Framework Detection
+
+| Framework | Detection Signals |
+|-----------|-------------------|
+| Vite | `vite.config.*` or `vite` in devDependencies |
+| Next.js | `next.config.*` or `next` in dependencies |
+| Angular | `angular.json` |
+| Create React App | `react-scripts` in dependencies |
+| Blazor WASM | `*.razor` + `WebAssembly` SDK in `*.csproj` |
+
+### Backend Proxy Dependencies
+
+If a proxy config points to a local backend, record the dependency so the compound debug configuration can order startup (backends before frontends).
+
+| Framework | Proxy Config Location |
+|-----------|----------------------|
+| Vite | `server.proxy` in `vite.config.*` |
+| Create React App | `"proxy"` in `package.json` |
+| Angular | `proxy.conf.json` |
+| Next.js | `rewrites()` in `next.config.*` |
@@ -0,0 +1,33 @@
+<!-- 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.
+
+# Runtimes
+
+> These are **common examples, not an exhaustive list**. If a service root uses a runtime
+> not listed here, identify it by the language and toolchain present (e.g. `rust`, `ruby`, etc.).
+
+## Detection Table
+
+| Detection Signals | Runtime | Version Source |
+|-------------------|---------|---------------|
+| `package.json` + `tsconfig.json` | **node-ts** | `engines.node` / `.nvmrc` / `.node-version` |
+| `package.json` (no `tsconfig.json`) | **node-js** | Same |
+| `*.csproj` | **dotnet** | `<TargetFramework>` element (e.g. `net8.0` → `8.0`) |
+| `requirements.txt`, `pyproject.toml`, or `Pipfile` | **python** | `.python-version` / `pyproject.toml` `requires-python` |
+| `pom.xml` or `build.gradle` | **java** | `<java.version>` / `sourceCompatibility` |
+| `go.mod` | **go** | `go` directive in `go.mod` |
+
+---
+
+## dotnet
+
+### Version Detection
+
+Read `<TargetFramework>` from the `.csproj` to determine the runtime version (e.g. `net8.0` → `8.0`).
+
+### Assembly Name
+
+Derive the assembly name for the plan's Service Label:
+
+1. If `<AssemblyName>` is set → use that value
+2. Otherwise → `.csproj` filename without extension (e.g. `Functions.csproj` → `Functions`)