Add request mocking, session management, and storage state management…

.github/copilot-instructions.md

@@ -57,7 +57,7 @@ infra/          → Azure infrastructure (Bicep)
 4. **Gherkin step definitions** — BDD behavioral tests, run against Aspire environment
 5. **Smoke tests** — post-deployment verification (per increment)
 
-> **All Cucumber and Playwright tests run against the Aspire environment** (`aspire run`), which orchestrates API and Web services identically to production.
+> **All Cucumber and Playwright tests run against the Aspire environment** (`aspire start` + `aspire wait`), which orchestrates API and Web services identically to production.
 > **Iterative delivery:** Each increment goes through the full test → implement → deploy cycle. After each increment, ALL tests pass and the app is deployed.
 
 ## Human Gates

.github/skills/aspire/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: aspire
+description: "Orchestrates Aspire distributed applications using the Aspire CLI for running, debugging, and managing distributed apps. USE FOR: aspire start, aspire stop, start aspire app, aspire describe, list aspire integrations, debug aspire issues, view aspire logs, add aspire resource, aspire dashboard, update aspire apphost. DO NOT USE FOR: non-Aspire .NET apps (use dotnet CLI), container-only deployments (use docker/podman), Azure deployment after local testing (use azure-deploy skill). INVOKES: Aspire CLI commands (aspire start, aspire describe, aspire otel logs, aspire docs search, aspire add), bash. FOR SINGLE OPERATIONS: Use Aspire CLI commands directly for quick resource status or doc lookups."
+---
+
+# Aspire Skill
+
+This repository uses Aspire to orchestrate its distributed application. Resources are defined in the AppHost project (`apphost.cs` or `apphost.ts`).
+
+## CLI command reference
+
+| Task | Command |
+|---|---|
+| Start the app | `aspire start` |
+| Start isolated (worktrees) | `aspire start --isolated` |
+| Restart the app | `aspire start` (stops previous automatically) |
+| Wait for resource healthy | `aspire wait <resource>` |
+| Stop the app | `aspire stop` |
+| List resources | `aspire describe` or `aspire resources` |
+| Run resource command | `aspire resource <resource> <command>` |
+| Start/stop/restart resource | `aspire resource <resource> start|stop|restart` |
+| View console logs | `aspire logs [resource]` |
+| View structured logs | `aspire otel logs [resource]` |
+| View traces | `aspire otel traces [resource]` |
+| Logs for a trace | `aspire otel logs --trace-id <id>` |
+| Add an integration | `aspire add` |
+| List running AppHosts | `aspire ps` |
+| Update AppHost packages | `aspire update` |
+| Search docs | `aspire docs search <query>` |
+| Get doc page | `aspire docs get <slug>` |
+| List doc pages | `aspire docs list` |
+| Environment diagnostics | `aspire doctor` |
+| List resource MCP tools | `aspire mcp tools` |
+| Call resource MCP tool | `aspire mcp call <resource> <tool> --input <json>` |
+
+Most commands support `--format Json` for machine-readable output. Use `--apphost <path>` to target a specific AppHost.
+
+## Key workflows
+
+### Running in agent environments
+
+Use `aspire start` to run the AppHost in the background. When working in a git worktree, use `--isolated` to avoid port conflicts and to prevent sharing user secrets or other local state with other running instances:
+
+```bash
+aspire start --isolated
+```
+
+Use `aspire wait <resource>` to block until a resource is healthy before interacting with it:
+
+```bash
+aspire start --isolated
+aspire wait myapi
+```
+
+Relaunching is safe — `aspire start` automatically stops any previous instance. Re-run `aspire start` whenever changes are made to the AppHost project.
+
+### Debugging issues
+
+Before making code changes, inspect the app state:
+
+1. `aspire describe` — check resource status
+2. `aspire otel logs <resource>` — view structured logs
+3. `aspire logs <resource>` — view console output
+4. `aspire otel traces <resource>` — view distributed traces
+
+### Adding integrations
+
+Use `aspire docs search` to find integration documentation, then `aspire docs get` to read the full guide. Use `aspire add` to add the integration package to the AppHost.
+
+After adding an integration, restart the app with `aspire start` for the new resource to take effect.
+
+### Using resource MCP tools
+
+Some resources expose MCP tools (e.g. `WithPostgresMcp()` adds SQL query tools). Discover and call them via CLI:
+
+```bash
+aspire mcp tools                                              # list available tools
+aspire mcp tools --format Json                                # includes input schemas
+aspire mcp call <resource> <tool> --input '{"key":"value"}'   # invoke a tool
+```
+
+## Important rules
+
+- **Always start the app first** (`aspire start`) before making changes to verify the starting state.
+- **To restart, just run `aspire start` again** — it automatically stops the previous instance. NEVER use `aspire stop` then `aspire run`. NEVER use `aspire run` at all.
+- Use `--isolated` when working in a worktree.
+- **Avoid persistent containers** early in development to prevent state management issues.
+- **Never install the Aspire workload** — it is obsolete.
+- Prefer `aspire.dev` and `learn.microsoft.com/dotnet/aspire` for official documentation.
+
+## Playwright CLI
+
+If configured, use Playwright CLI for functional testing of resources. Get endpoints via `aspire describe`. Run `playwright-cli --help` for available commands.

.github/skills/e2e-generation/SKILL.md

@@ -148,7 +148,7 @@ Apply tags consistently:
 
 All e2e tests run against the **Aspire-managed environment**. The Playwright config already handles this:
 
-- `webServer` in `e2e/playwright.config.ts` starts `aspire run --project ../apphost.cs`
+- `webServer` in `e2e/playwright.config.ts` starts `aspire start` + `aspire wait web`
 - Base URL defaults to `http://localhost:3001` (Aspire web port)
 - API is available at `http://localhost:5001` (Aspire API port)
 - Running locally via Aspire is **non-negotiable** — never start API/Web individually

.github/skills/gherkin-generation/SKILL.md

@@ -56,7 +56,7 @@ When operating in `capture-existing` mode, follow these steps instead of the sta
 
 1. **Read the FRD's "Current Implementation" section** — this is the primary input. Understand what the feature does today, including its endpoints, UI flows, data handling, and known limitations.
 2. **Read extracted API contracts** (`specs/contracts/api/*.yaml`) — use the extracted OpenAPI specs to understand exact endpoint behavior: request/response shapes, status codes, and error responses.
-3. **Observe actual behavior (if app is running)** — if the application is available (e.g., via `aspire run`), make requests or walk through flows to verify your understanding. Resolve any discrepancies between docs and actual behavior in favor of actual behavior.
+3. **Observe actual behavior (if app is running)** — if the application is available (e.g., via `aspire start`), make requests or walk through flows to verify your understanding. Resolve any discrepancies between docs and actual behavior in favor of actual behavior.
 4. **Generate happy-path scenarios** — write scenarios for the primary success paths of each feature area as it works today.
 5. **Generate known edge-case scenarios** — document edge cases that the current implementation handles (or mishandles). Only include edge cases you can confirm exist.
 6. **Generate error-handling scenarios** — document how the app currently responds to invalid input, unauthorized access, missing resources, etc.

.github/skills/implementation/SKILL.md

@@ -142,7 +142,7 @@ See `references/web-slice.md` for the full procedure.
 ## Integration Slice — Overview
 
 Wire API + Web together via the Aspire environment. Replace all mocks with real
-API calls. All tests run against `aspire run`.
+API calls. All tests run against `aspire start`.
 
 **Key rules:**
 - **Mock removal is mandatory.** No mock API calls may remain after this slice.

.github/skills/implementation/references/integration-slice.md

@@ -5,7 +5,7 @@
 After BOTH the API and Web slices are complete (all their tests green), wire
 them together and verify end-to-end behavior. The key task is **replacing any
 mock API calls in the Web slice with real fetch calls to the running API**. All
-integration tests run against the **Aspire environment** (`aspire run`), which
+integration tests run against the **Aspire environment** (`aspire start`), which
 orchestrates API and Web services identically to production.
 
 ## Procedure
@@ -33,7 +33,9 @@ orchestrates API and Web services identically to production.
          and the real API responses — the contract types are the source of truth.
 
 3.  Start the Aspire environment (if not already running):
-      aspire run
+      aspire start
+      aspire wait api --status healthy
+      aspire wait web --status healthy
 
 4.  Verify Playwright browsers are installed:
       npx playwright install --with-deps
@@ -107,7 +109,9 @@ Before marking the integration slice as done, verify:
 
 ```bash
 # Start Aspire environment
-aspire run
+aspire start
+aspire wait api --status healthy
+aspire wait web --status healthy
 
 # Cucumber for a specific feature
 npx cucumber-js --tags "@{feature}"

.github/skills/implementation/references/stack-patterns.md

@@ -93,7 +93,9 @@ cd src/web && npx vitest run
 
 ```bash
 # Start Aspire environment
-aspire run
+aspire start
+aspire wait api --status healthy
+aspire wait web --status healthy
 
 # Cucumber for a specific feature
 npx cucumber-js --tags "@{feature}"