chore: modernize repository AI guidance

.agents/skills/client-integration-authoring/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: client-integration-authoring
+description: Guides authoring and reviewing CommunityToolkit Aspire client integrations, including registration shape, configuration, keyed services, health checks, telemetry, READMEs, examples, and tests.
+---
+
+# Aspire client integration authoring
+
+Use this skill when creating, modifying, or reviewing `CommunityToolkit.Aspire.*` client integration packages whose extension methods register consuming-application services.
+
+## First step: classify the integration
+
+Inspect nearby client integrations and classify the requested work:
+
+1. **Client lifetime:** singleton, scoped, transient, SDK-managed, or `HttpClient`-backed.
+2. **Configuration source:** connection string, configuration section, explicit settings, or a combination.
+3. **Registration shape:** default service, keyed service, custom service key, or a fluent builder.
+4. **Optional concerns:** health checks, tracing/metrics, Microsoft.Extensions.AI adapters, Native AOT, or multiple logical clients.
+
+Do not force every integration into one template. Read [patterns](references/patterns.md) and apply only the capabilities supported by the underlying client library and demonstrated by nearby integrations.
+
+## Authoring workflow
+
+1. Inspect two existing client integrations with the closest registration and configuration shape.
+2. Define the smallest public API that follows the underlying SDK and repository conventions.
+3. Implement settings binding, connection-string override, and the configuration callback in a predictable order.
+4. Add default and keyed registration only when both are useful and can behave consistently.
+5. Add health checks and telemetry only when the integration can implement them reliably.
+6. Add focused tests and documentation using [testing and documentation](references/testing-and-documentation.md).
+7. Add source, test, and example projects to `CommunityToolkit.Aspire.slnx` when new projects are created.
+8. Validate with the narrowest relevant build and test commands.
+
+## Non-negotiable conventions
+
+- Client extension methods use the `Microsoft.Extensions.Hosting` namespace.
+- Client packages use `CommunityToolkit.Aspire.[IntegrationName]` naming and include the `client` package tag.
+- Public APIs require XML documentation.
+- Validate public inputs with the throw helpers used by nearby integrations.
+- Do not create or manually edit generated `*/api/*.cs` files.
+- Fail with a clear configuration error when a client cannot be constructed unless an established integration pattern intentionally defers missing-configuration handling; do not silently create an invalid client.
+- Keep health checks lightweight and cancellation-aware.
+- Avoid adding health-check, telemetry, or HTTP dependencies when the integration does not use them.
+
+## Review workflow
+
+Review for behavioral correctness rather than template conformity:
+
+- configuration precedence and missing-configuration behavior;
+- service lifetime and keyed/default symmetry;
+- duplicated registrations or health checks;
+- disposal and `HttpClient` usage;
+- telemetry opt-out behavior;
+- health-check names, timeouts, and failure handling;
+- README examples that match the actual API; and
+- tests that cover the supported registration shapes.

.agents/skills/client-integration-authoring/references/patterns.md

@@ -0,0 +1,46 @@
+# Client integration patterns
+
+## Configuration order
+
+The common order is:
+
+1. Create the settings object.
+2. Bind the integration's configuration section.
+3. Apply a named connection string when present.
+4. Invoke the caller's configuration delegate.
+5. Register services, telemetry, and health checks.
+
+Use the actual settings type and connection-string format of the SDK. Some integrations store a raw connection string, some parse an endpoint, and others construct SDK options.
+
+## Registration shapes
+
+Choose the shape supported by the client:
+
+- **Singleton:** long-lived, thread-safe SDK clients such as KurrentDB.
+- **Scoped:** connection/session objects such as DuckDB connections.
+- **`HttpClient`-backed:** use `IHttpClientFactory` when the SDK accepts `HttpClient` or requires HTTP handler lifetime management.
+- **SDK-managed registration:** use the SDK's DI extensions when they preserve the desired lifetime and keyed behavior.
+- **Fluent builder:** return a builder only when follow-up features such as chat or embedding adapters need to compose from the registered client.
+
+Default and keyed methods should use one internal registration path where practical. A custom object service-key overload is useful only when the repository pattern or SDK use case needs it.
+
+## Health checks
+
+- Prefer a maintained health-check package when it accurately supports the service.
+- Otherwise implement the smallest low-impact connectivity operation.
+- Respect cancellation and configured timeouts.
+- Use stable names and make keyed registrations distinguishable.
+- Do not register a health check when required configuration is absent unless the established integration pattern intentionally defers the failure until host startup.
+
+## Telemetry
+
+- Register only telemetry the SDK actually emits.
+- Preserve the integration's disable flags.
+- Avoid duplicate instrumentation when multiple keyed clients are added.
+
+## Examples in this repository
+
+- `CommunityToolkit.Aspire.KurrentDB` demonstrates singleton, keyed registration, tracing, health checks, and connection-string precedence.
+- `CommunityToolkit.Aspire.DuckDB.NET.Data` demonstrates scoped connection registration.
+- `CommunityToolkit.Aspire.OllamaSharp` demonstrates `HttpClient` usage and a fluent builder for Microsoft.Extensions.AI adapters.
+- `CommunityToolkit.Aspire.SurrealDb` demonstrates SDK-managed registration and deferred handling when options are absent.

.agents/skills/client-integration-authoring/references/testing-and-documentation.md

@@ -0,0 +1,40 @@
+# Client integration testing and documentation
+
+## Tests
+
+Cover the behavior the integration exposes:
+
+- configuration-section binding;
+- connection-string override;
+- caller configuration override;
+- default service registration;
+- keyed registration and key isolation;
+- expected service lifetime;
+- missing required configuration;
+- health-check registration and disable behavior;
+- telemetry registration and disable behavior; and
+- fluent builder features when present.
+
+Use the nearest client integration test project as the structural reference. Add container-backed tests only when the client behavior cannot be proven without the service, and mark Docker-dependent tests with `[RequiresDocker]`.
+
+When adding a test project, run:
+
+```bash
+./eng/testing/generate-test-list-for-workflow.sh --json
+```
+
+The reusable test matrix is `.github/workflows/tests.yaml`.
+
+## README
+
+Document only supported behavior:
+
+1. Package purpose and installation.
+2. Minimal `IHostApplicationBuilder` registration.
+3. Expected connection string and configuration section.
+4. Keyed registration if supported.
+5. Health-check and telemetry behavior when present.
+6. Fluent or Microsoft.Extensions.AI adapters when present.
+7. A link to the matching example.
+
+Keep snippets aligned with the compiled public API. Do not advertise a generic template capability that the integration does not implement.

.agents/skills/hosting-integration-authoring/resources/testing-and-readmes.md

@@ -27,7 +27,7 @@ DO test:
 - Preflight failure paths for missing CLI, missing auth/context, missing registry access, disabled target APIs/services, and insufficient permissions.
 - Polyglot exports when exported API shape changes, including analyzer diagnostics and generated `.d.ts` signatures.
 - Controller/reconciler command serialization, conflict detection, command state transitions, cancellation, drift coalescing, and per-resource completion behavior when the integration owns shared external state.
-- Solution and CI wiring for new projects. Add new source, test, and example projects to `CommunityToolkit.Aspire.slnx`; when a new test project is added, run `./eng/testing/generate-test-list-for-workflow.sh` and include the `.github/workflows/tests.yml` update.
+- Solution and CI wiring for new projects. Add new source, test, and example projects to `CommunityToolkit.Aspire.slnx`; when a new test project is added, run `./eng/testing/generate-test-list-for-workflow.sh --json` and verify the reusable `.github/workflows/tests.yaml` matrix discovers it.
 
 DON'T: