feat: improve domain scaffolding with container-first deploy, uniqueString, and lessons learned

- Add Lessons Learned section to agent with 8 codified patterns from Code Quality iteration
- Container-first deployment: all 5 demo apps deploy as Docker containers via ACR + Web App for Containers
- Global uniqueness: all Bicep templates use uniqueString(resourceGroup().id) for multi-student workshops
- OIDC JSON fix: temp file pattern for federated credentials (PowerShell quote mangling)
- Environment consistency: standardize on 'prod' (not 'production') across workflows and credentials
- GitHub Pages fixes: remote_theme, correct baseurl, github-pages gem
- Scanner repo secrets: deploy-all.yml needs OIDC secrets on scanner repo too
- Codespace-first philosophy: all apps runnable locally via docker build/run
- Per-domain OIDC app: avoid 20-credential limit by not sharing across domains
- Updated Bicep template with ACR + Web App for Containers + uniqueString outputs
- Updated deploy workflow template to use az acr build + container deploy pattern
- Added Dockerfile requirements, port conventions, and Run Locally section specs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: emmanuelknafo

agents/domain-scaffolder.agent.md

@@ -81,8 +81,10 @@ Generate the complete `{domain}-scan-demo-app` repository structure following th
 8. Create `infra/storage.bicep` for ADLS Gen2 storage.
 9. Create `docs/` with overview, Power BI data model, and workshop setup documentation.
 10. Create `README.md` with project overview.
-11. Generate `.github/workflows/deploy.yml` for each demo app directory. Each deploy workflow MUST include: OIDC login, resource group creation via Bicep, language-specific build step, App Service deployment, health check, and `GITHUB_STEP_SUMMARY` output. Use the per-language deploy workflow template from the scaffolding skill.
-12. Include repository metadata in bootstrap scripts: set topics array, repository description, and enable GitHub Advanced Security code scanning for each demo app repo. Follow the repository metadata conventions from the scaffolding instructions.
+11. Generate `.github/workflows/deploy.yml` for each demo app directory. Each deploy workflow MUST use **containerized deployment**: Docker build → ACR push → Web App for Containers deploy. Include: OIDC login, resource group creation via Bicep, `az acr build`, deploy to Web App for Containers via `azure/webapps-deploy@v3` with `images:` parameter, health check, and `GITHUB_STEP_SUMMARY` output. Use the container deploy workflow template from the scaffolding skill.
+12. All `infra/main.bicep` files MUST use `uniqueString(resourceGroup().id)` for globally-scoped resource names (ACR, App Service, App Service Plan). Bicep MUST provision ACR + Web App for Containers (Linux, Docker), not Oryx code-deploy App Service.
+13. Include repository metadata in bootstrap scripts: set topics array, repository description, enable GitHub Advanced Security code scanning for each demo app repo, and **set OIDC secrets on the scanner repo** in addition to individual app repos. Follow the repository metadata conventions from the scaffolding instructions.
+14. All demo apps MUST be runnable locally in GitHub Codespaces via `docker build -t app . && docker run -p 3000:3000 app` without requiring Azure deployment.
 
 ### Step 5: Generate Workshop Repository
 
@@ -110,6 +112,8 @@ Configure repository-level settings that must be applied after content is pushed
 3. Set **repository description** on both repos using `gh repo edit --description`.
 4. Set **repository topics** on both repos using `gh repo edit --add-topic` for each topic in the domain topics array.
 5. Set the **website URL** on the workshop repo to its GitHub Pages URL.
+6. Set **OIDC secrets** (`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`) on the **scanner repo** — the `deploy-all.yml` runs there.
+7. Create the **`prod` environment** on the scanner repo (not `production` — match the federated credential subject).
 
 ### Step 7: Produce Summary
 
@@ -156,9 +160,73 @@ After scaffolding is complete:
 - Hand off to **CodeQualityDetector** to scan generated sample apps and verify they contain sufficient intentional violations (minimum 15 findings per app).
 - Hand off to **TestGenerator** to generate initial test suites for the sample apps to establish baseline coverage metrics.
 
+## Lessons Learned from Prior Iterations
+
+Apply these lessons when scaffolding any new domain. These were discovered during the Code Quality domain scaffolding and MUST be codified in all generated artifacts.
+
+### 1. Container-First Deployment (Web App for Containers)
+
+All 5 demo apps MUST deploy as **Docker containers** to Azure Web App for Containers. Do NOT use Oryx-based source deployment — it fails for Go and is fragile for other languages. The uniform container approach works for all languages and mirrors production patterns.
+
+- Every demo app already has a `Dockerfile` — use it as the deployment artifact.
+- Use Azure Container Registry (ACR) to push images, then deploy via `azure/webapps-deploy@v3` with the `images` parameter.
+- The ACR name MUST use Bicep `uniqueString(resourceGroup().id)` for global uniqueness.
+
+### 2. Global Uniqueness via Bicep `uniqueString()`
+
+Many students run workshops simultaneously. All globally-scoped Azure resource names MUST include `uniqueString(resourceGroup().id)` to avoid collisions:
+
+- **ACR**: `acr${uniqueString(resourceGroup().id)}` (3–50 chars, alphanumeric only)
+- **App Service**: `${appName}-${uniqueString(resourceGroup().id)}`
+- **App Service Plan**: `plan-${appName}-${uniqueString(resourceGroup().id)}`
+- **Storage Account**: `st${uniqueString(resourceGroup().id)}` (3–24 chars, alphanumeric only)
+
+### 3. OIDC JSON Quoting in PowerShell
+
+When passing JSON to Azure CLI from PowerShell, NEVER use inline `ConvertTo-Json -Compress`. PowerShell mangles the quotes. Always write to a temp file and pass `@$tempFile`:
+
+```powershell
+$credParams = @{ name = $credName; issuer = $issuer; subject = $subject; audiences = @($audience) }
+$tempFile = [System.IO.Path]::GetTempFileName()
+$credParams | ConvertTo-Json | Set-Content -Path $tempFile -Encoding UTF8
+az ad app federated-credential create --id $appId --parameters "@$tempFile"
+Remove-Item -Path $tempFile -Force
+```
+
+### 4. Consistent Environment Names
+
+OIDC federated credentials and GitHub Actions workflows MUST use the same environment name. Standardize on `prod` (not `production`):
+
+- Federated credential subject: `repo:{org}/{repo}:environment:prod`
+- Workflow: `environment: prod`
+- GitHub environment: `gh api repos/{org}/{repo}/environments/prod --method PUT`
+
+### 5. Secrets on Scanner Repo
+
+The `deploy-all.yml` workflow runs on the **scanner repo** (`{domain}-scan-demo-app`), not on individual demo app repos. The bootstrap script MUST also set `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_SUBSCRIPTION_ID` on the scanner repo itself, and create the `prod` environment there.
+
+### 6. GitHub Pages Configuration
+
+For project sites (non-org pages), workshop `_config.yml` MUST:
+
+- Set `baseurl: "/{repo-name}"` (not empty string)
+- Use `remote_theme: just-the-docs/just-the-docs` (not `theme: just-the-docs`)
+- Use `github-pages` gem (not `jekyll` gem directly) in the `Gemfile`
+
+### 7. Codespace-First Philosophy
+
+All demo apps MUST be runnable and testable inside GitHub Codespaces without Azure deployment. Students can always `docker build` and `docker run` locally in a Codespace. Lab instructions SHOULD include a "Run Locally" alternative for each deploy step.
+
+### 8. Per-Domain OIDC App Registration
+
+Azure AD federated identity credentials have a **maximum of 20 per app**. Do NOT share a single OIDC app across multiple domains. Each domain MUST create its own dedicated app registration (e.g., `code-quality-scan-demo-app-oidc`).
+
 ## Conventions
 
 Follow all conventions defined in `instructions/domain-scaffolding.instructions.md` for naming, SARIF standards, bootstrap scripts, CI/CD pipelines, Power BI PBIP, workshop labs, demo app violations, and screenshot automation.
 
 - **PowerShell Only**: All generated commands in screenshot manifests, lab instructions, bootstrap scripts, and CI/CD pipelines MUST use PowerShell Core syntax. Never generate Unix-only commands (`head`, `tail`, `cat`, `2>/dev/null`, `/tmp/`, `./script`).
 - **Idempotent Bootstrap**: All bootstrap scripts MUST be safe to re-run without errors. Every resource creation step MUST check for existing resources before creating.
+- **Container-First**: All demo apps deploy as Docker containers via ACR + Web App for Containers. Never use Oryx source deployment.
+- **Global Uniqueness**: All Azure resource names with global scope MUST use `uniqueString(resourceGroup().id)` in Bicep.
+- **Codespace-Ready**: All demo apps MUST be buildable and runnable in Codespaces via `docker build && docker run`.

instructions/domain-scaffolding.instructions.md

@@ -215,25 +215,25 @@ Each sample app directory (`{prefix}-demo-app-001` through `005`) is pushed to i
 
 ### Deploy Workflow Requirements
 
+Every per-app deploy.yml MUST use **containerized deployment** (Web App for Containers). Do NOT use Oryx-based source deployment — it fails for Go and is fragile for other languages. The container approach works identically for all 5 languages and mirrors production deployment patterns.
+
 Every per-app deploy.yml MUST include these stages:
 
 1. **Azure Login** — OIDC federated credential login (`azure/login@v2`)
 2. **Resource Group** — Create or verify resource group via `az group create`
-3. **Infrastructure** — Deploy `infra/main.bicep` via `az deployment group create`
-4. **Build** — Language-specific build step (see table below)
-5. **Deploy** — Deploy to Azure App Service or Container App
+3. **Infrastructure** — Deploy `infra/main.bicep` via `az deployment group create` (provisions ACR + Web App for Containers)
+4. **Build & Push** — Build Docker image and push to ACR via `az acr build`
+5. **Deploy** — Deploy container to Web App for Containers via `azure/webapps-deploy@v3` with `images:` parameter
 6. **Health Check** — Verify the deployed app responds with HTTP 200
 7. **Summary** — Write deployed URL and status to `$GITHUB_STEP_SUMMARY`
 
 ### Language-Specific Build Steps
 
-| Language | Build Command | Output |
-|----------|---------------|--------|
-| C# | `dotnet publish -c Release -o ./publish` | `./publish/` directory |
-| Python | `pip install -r requirements.txt` | In-place |
-| Java | `.\gradlew.bat build` (or `mvn package`) | `build/libs/*.jar` or `target/*.jar` |
-| TypeScript | `npm ci && npm run build` | `dist/` or `.next/` directory |
-| Go | `go build -o ./app .` | `./app` binary |
+Language-specific build steps are **no longer needed** in the deploy workflow because all apps are built via `docker build` using their `Dockerfile`. Each demo app MUST include a production-ready `Dockerfile`.
+
+### Deploy Workflow Environment Name
+
+All deploy workflows MUST use `environment: prod` (not `production`). This MUST match the OIDC federated credential subject: `repo:{org}/{repo}:environment:prod`. Mismatched environment names cause OIDC login failures.
 
 ### Workflow Permissions
 
@@ -243,6 +243,151 @@ permissions:
   contents: read
 ```
 
+## Global Uniqueness via Bicep `uniqueString()`
+
+Many workshop students deploy simultaneously to the same Azure subscription. All globally-scoped Azure resource names MUST include `uniqueString(resourceGroup().id)` in Bicep to avoid naming collisions.
+
+### Resources Requiring Global Uniqueness
+
+| Resource | Name Pattern | Bicep Expression |
+|----------|-------------|-----------------|
+| ACR | `acr{uniqueString}` | `'acr${uniqueString(resourceGroup().id)}'` |
+| App Service | `{appName}-{uniqueString}` | `'${appName}-${uniqueString(resourceGroup().id)}'` |
+| App Service Plan | `plan-{appName}-{uniqueString}` | `'plan-${appName}-${uniqueString(resourceGroup().id)}'` |
+| Storage Account | `st{uniqueString}` | `'st${uniqueString(resourceGroup().id)}'` |
+
+### Bicep Template Structure
+
+Every `infra/main.bicep` MUST:
+
+1. Accept a `appName` parameter for logical identification
+2. Use `uniqueString(resourceGroup().id)` for all globally-scoped names
+3. Provision **ACR** + **App Service Plan** (Linux) + **Web App for Containers**
+4. Output the computed ACR name, app name, and default hostname for use by the deploy workflow
+5. Use `linuxFxVersion: 'DOCKER|${acrName}.azurecr.io/${appName}:latest'` for container configuration
+
+### Deploy Workflow Deriving Names from Bicep Outputs
+
+Deploy workflows MUST read ACR name and app name from Bicep deployment outputs rather than hardcoding them:
+
+```yaml
+- name: Deploy Infrastructure
+  id: infra
+  run: |
+    outputs=$(az deployment group create \
+      --resource-group ${{ env.AZURE_RG }} \
+      --template-file infra/main.bicep \
+      --parameters appName=${{ env.APP_NAME }} \
+      --query 'properties.outputs' -o json)
+    echo "acrName=$(echo $outputs | jq -r '.acrName.value')" >> $GITHUB_OUTPUT
+    echo "appServiceName=$(echo $outputs | jq -r '.appServiceName.value')" >> $GITHUB_OUTPUT
+```
+
+## Containerized Deployment Conventions
+
+### Dockerfile Requirements
+
+Every demo app MUST include a `Dockerfile` that:
+
+1. Uses a multi-stage build where appropriate (e.g., build stage + runtime stage)
+2. Exposes a PORT (default `3000` for Node, `5000` for Python, `8080` for Java/Go/.NET)
+3. Sets a `HEALTHCHECK` instruction or relies on the App Service health probe
+4. Is optimized for layer caching (dependencies before source code)
+
+### ACR Build Pattern
+
+Use `az acr build` instead of `docker build` + `docker push` — it avoids needing Docker-in-Docker in GitHub Actions runners:
+
+```yaml
+- name: Build and Push to ACR
+  run: |
+    az acr build \
+      --registry ${{ steps.infra.outputs.acrName }} \
+      --image ${{ env.APP_NAME }}:${{ github.sha }} \
+      --image ${{ env.APP_NAME }}:latest \
+      .
+```
+
+### Web App Container Deploy
+
+```yaml
+- name: Deploy to Web App
+  uses: azure/webapps-deploy@v3
+  with:
+    app-name: ${{ steps.infra.outputs.appServiceName }}
+    images: ${{ steps.infra.outputs.acrName }}.azurecr.io/${{ env.APP_NAME }}:${{ github.sha }}
+```
+
+## Codespace-First Philosophy
+
+All demo apps MUST be runnable and testable inside GitHub Codespaces without Azure deployment. This provides a zero-cost, zero-config development experience for workshop participants.
+
+### Requirements
+
+1. Every demo app MUST include a `README.md` section titled "Run Locally" with:
+   ```bash
+   docker build -t {prefix}-demo-app-NNN .
+   docker run -p 3000:3000 {prefix}-demo-app-NNN
+   ```
+2. Workshop lab instructions SHOULD include a "Run Locally in Codespace" alternative for each deploy step
+3. The workshop `.devcontainer/devcontainer.json` MUST include Docker-in-Docker feature for local builds
+
+## OIDC Script Conventions
+
+### JSON Quoting Fix
+
+When passing JSON to Azure CLI from PowerShell, NEVER use inline `ConvertTo-Json -Compress`. PowerShell mangles the quotes when interpolating. Always write to a temp file:
+
+```powershell
+$credParams = @{
+    name      = $credName
+    issuer    = "https://token.actions.githubusercontent.com"
+    subject   = $subject
+    audiences = @("api://AzureADTokenExchange")
+}
+$tempFile = [System.IO.Path]::GetTempFileName()
+$credParams | ConvertTo-Json | Set-Content -Path $tempFile -Encoding UTF8
+az ad app federated-credential create --id $appId --parameters "@$tempFile"
+Remove-Item -Path $tempFile -Force
+```
+
+### Per-Domain OIDC App Registration
+
+Azure AD federated identity credentials have a **maximum of 20 per app**. With 6+ repos × 3 subjects (main/dev/prod) = 18+, a shared OIDC app across domains will hit this limit. Each domain MUST create its own dedicated app registration.
+
+### Scanner Repo Secrets
+
+The `deploy-all.yml` workflow runs on the scanner repo (`{domain}-scan-demo-app`). The OIDC setup and bootstrap scripts MUST also:
+
+1. Set `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID` secrets on the scanner repo
+2. Create the `prod` environment on the scanner repo
+3. Add federated credentials for `repo:{org}/{domain}-scan-demo-app:environment:prod`
+
+## GitHub Pages Configuration (Workshop)
+
+### Jekyll Config
+
+Workshop `_config.yml` MUST use these settings for project sites:
+
+```yaml
+remote_theme: just-the-docs/just-the-docs
+baseurl: "/{repo-name}"    # MUST be /{repo-name} for project sites, NOT empty string
+url: "https://{org}.github.io"
+```
+
+Do NOT use `theme: just-the-docs` — it only works locally. Use `remote_theme` for GitHub Pages compatibility.
+
+### Gemfile
+
+Workshop `Gemfile` MUST use the `github-pages` gem:
+
+```ruby
+source "https://rubygems.org"
+gem "github-pages", group: :jekyll_plugins
+```
+
+Do NOT use `gem "jekyll"` or `gem "just-the-docs"` directly — they may not be compatible with GitHub Pages.
+
 ## Repository Metadata
 
 Both generated repositories MUST have metadata configured via bootstrap scripts or repository setup steps.