feat(api): generate synchronized Postman collection

.github/pull_request_template.md

@@ -13,6 +13,7 @@
 - Build succeeds
 - Tests pass
 - Relevant documentation updated
+- Postman artifacts regenerated, or no HTTP API/Postman input changed
 - No unnecessary breaking change introduced
 - Desktop and mobile smoke test completed against the local executable
 

.github/workflows/ci.yml

@@ -94,8 +94,14 @@ jobs:
             nuget-${{ runner.os }}-
       - name: Restore web tests
         run: dotnet restore tests/Agentstration.Web.Tests/Agentstration.Web.Tests.csproj -p:NuGetAudit=true -p:NuGetAuditMode=all
+      - name: Restore Postman generator
+        run: dotnet restore tools/Agentstration.Postman/Agentstration.Postman.csproj -p:NuGetAudit=true -p:NuGetAuditMode=all
       - name: Build web tests
         run: dotnet build tests/Agentstration.Web.Tests/Agentstration.Web.Tests.csproj --configuration Release --no-restore
+      - name: Build Postman generator
+        run: dotnet build tools/Agentstration.Postman/Agentstration.Postman.csproj --configuration Release --no-restore
+      - name: Verify generated Postman artifacts on Windows
+        run: dotnet run --project tools/Agentstration.Postman --configuration Release --no-build -- --check
       - name: Verify Windows host lifecycle
         run: dotnet tests/Agentstration.Web.Tests/bin/Release/net10.0/Agentstration.Web.Tests.dll --filter "FullyQualifiedName~QuartzHostLifecycleTests|FullyQualifiedName~StartupDoesNotCreateLegacyDataJson" --progress off
 
@@ -139,6 +145,9 @@ jobs:
       - name: Build Agentstration
         if: needs.changes.outputs.dotnet == 'true'
         run: dotnet build Agentstration.slnx --configuration Release --no-restore
+      - name: Verify generated Postman artifacts
+        if: needs.changes.outputs.dotnet == 'true'
+        run: dotnet run --project tools/Agentstration.Postman --configuration Release --no-build -- --check
       - name: Test Agentstration
         if: needs.changes.outputs.dotnet == 'true'
         run: dotnet test Agentstration.slnx --configuration Release --no-build

AGENTS.md

@@ -203,6 +203,16 @@ Use `--launch-profile http-NoBootstrap` instead when the test must preserve or e
 5. Add an ADR under `docs/decisions/` for a significant architectural choice; do not rewrite an accepted ADR to hide a new decision.
 6. Build and test after meaningful increments, and report any validation that could not be run.
 
+## HTTP API and Postman Contract
+
+OpenAPI is the source of truth for the HTTP API reference. `dev/postman/Agentstration.postman_collection.json` is a generated consumer artifact and must remain synchronized with it.
+
+- When adding, changing, or removing an HTTP route, request or response contract, parameter, media type, authentication rule, or other observable HTTP behavior, run `dotnet run --project tools/Agentstration.Postman` and commit the regenerated Postman artifacts in the same change.
+- Update the relevant curated file under `dev/postman/scenarios/` when an API behavior change affects an executable workflow, captured identifier, ETag, assertion, or cleanup step.
+- Do not edit the generated `API Reference` folder directly. Improve endpoint OpenAPI metadata or the generator instead.
+- Before handoff, run `dotnet run --project tools/Agentstration.Postman -- --check` and report the result in the pull request. If the command is not applicable because no HTTP API or Postman input changed, state that explicitly.
+- Keep committed environments free of credentials, tokens, cookies, secret values, and machine-specific identifiers. Use separate `scheme`, `host`, and `port` variables for endpoint configuration.
+
 ## Issue Creation
 
 When creating or updating a GitHub issue, treat the forms under `.github/ISSUE_TEMPLATE/` as the canonical structure, including when using the GitHub API:

Agentstration.slnx

@@ -67,4 +67,7 @@
     <Project Path="tests/Agentstration.Workplace.Components.Tests/Agentstration.Workplace.Components.Tests.csproj" />
     <Project Path="tests/Agentstration.Workplace.Web.Tests/Agentstration.Workplace.Web.Tests.csproj" />
   </Folder>
+  <Folder Name="/tools/">
+    <Project Path="tools/Agentstration.Postman/Agentstration.Postman.csproj" />
+  </Folder>
 </Solution>

README.md

@@ -204,6 +204,8 @@ dotnet build Agentstration.slnx --configuration Release
 dotnet test Agentstration.slnx --configuration Release
 ```
 
+The complete Postman collection and Local/Docker environment templates are under [`dev/postman`](dev/postman/README.md). Regenerate them from the authoritative runtime OpenAPI document with `dotnet run --project tools/Agentstration.Postman`.
+
 Warnings are treated as errors, .NET analyzers are enabled and NuGet audit findings fail restore. The default tests are designed to remain offline and cost-free; real-provider smoke tests are opt-in.
 
 ## Documentation