docs: how-to guides for 8 adapters

[Pomdapis]

Summary

Closes POM-184. Replaces the placeholders from POM-180 with full how-to content for all 8 first-party adapters.

Pages

Adapter	Length	Highlights
aspnetcore.md	~50 lines	TenantValidationMiddleware options, ordering with auth/authz
postgresql.md	~80 lines	Connection pool tuning table, PgBouncer caveat
redis.md	~60 lines	Multi-tenant key namespacing, TLS warning
zitadel.md	~75 lines	SA key vs PAT vs client-credentials, redirect URI templates
stripe.md	~65 lines	Webhook signature validation, API version pinning, PII handling
lemonsqueezy.md	~55 lines	License key API specifics, JSON:API vs plain JSON
listmonk.md	~55 lines	PII in logs, basic auth over HTTPS only
openrouter.md	~70 lines	Model prefixing, latency tail, prompt logging hazard

Template

Every page follows the same structure: Install → Configuration → Usage → Gotchas → See also. Configuration tables are derived from each adapter's *Options.cs XML doc — single source of truth.

Validation

DocFX local build: 0 errors, 12 warnings.

The warnings are cosmetic: DocFX checks ../api/*.html links against build input content, but those files are generated as build output. Verified manually that the corresponding .yml files (input) and .html files (output) exist for every link, so the links resolve correctly on the deployed site.

Test plan

• docfx metadata + build succeeds locally
• Configuration tables match the actual *Options.cs files
• Cross-links to concept pages and ADRs are valid
• CI green
• Pages live at /main/adapters/<name>.html

[Copilot]

Pull request overview

Replaces “coming soon” placeholders with full DocFX how-to pages for the 8 first-party adapters, intended to guide installation, configuration, usage, and common pitfalls.

Changes:

• Added detailed adapter documentation pages under docs/adapters/ following a consistent structure.
• Included configuration examples + options tables for each adapter.
• Added usage snippets and “gotchas” sections with cross-links to API reference/concepts/ADRs.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
docs/adapters/aspnetcore.md	Adds install/config/usage/gotchas for ASP.NET Core integration (tenant middleware, etc.).
docs/adapters/postgresql.md	Adds PostgreSQL adapter how-to with options + event store usage example.
docs/adapters/redis.md	Adds Redis adapter how-to with options + usage/gotchas.
docs/adapters/zitadel.md	Adds Zitadel adapter how-to with auth/config options + provisioning usage snippet.
docs/adapters/stripe.md	Adds Stripe adapter how-to with options + billing/webhook guidance.
docs/adapters/lemonsqueezy.md	Adds LemonSqueezy adapter how-to with billing + license service usage.
docs/adapters/listmonk.md	Adds Listmonk adapter how-to with newsletter/email usage + security gotchas.
docs/adapters/openrouter.md	Adds OpenRouter adapter how-to with options + completion usage/gotchas.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The “Default” column should reflect the actual default value. StripeOptions.WebhookSigningSecret defaults to an empty string (""), not “strongly recommended”; the recommendation belongs in the description while the default remains _empty_/"" (since empty disables signature validation).

Suggested change

	| `WebhookSigningSecret` | _strongly recommended_ | `whsec_…` — when empty, signature validation is skipped (dev only) |
	| `WebhookSigningSecret` | `""` | Strongly recommended: set to `whsec_…`; when empty, signature validation is skipped (dev only) |

[Copilot]

The usage snippet calls billing.EnsureCustomerAsync(...) and billing.StartSubscriptionAsync(...), but IBillingService doesn’t define those methods (it has UpsertCustomerAsync, CreateCheckoutSessionAsync, etc.). This example should be updated to use the real Compendium.Abstractions.Billing APIs (and ISubscriptionService if you want to show subscription operations).

Suggested change

	: ICommandHandler<StartSubscriptionCommand>
	{
	public async Task<Result> Handle(StartSubscriptionCommand cmd, CancellationToken ct)
	{
	var customerResult = await billing.EnsureCustomerAsync(
	email: cmd.Email,
	tenantId: cmd.TenantId,
	ct);
	if (customerResult.IsFailure) return customerResult.Error;
	var subResult = await billing.StartSubscriptionAsync(
	customerResult.Value.Id, cmd.PriceId, ct);
	return subResult.IsSuccess ? Result.Success() : subResult.Error;
	{
	public async Task<Result<string>> Handle(StartSubscriptionCommand cmd, CancellationToken ct)
	{
	var customerResult = await billing.UpsertCustomerAsync(
	email: cmd.Email,
	tenantId: cmd.TenantId,
	ct);
	if (customerResult.IsFailure) return customerResult.Error;
	var sessionResult = await billing.CreateCheckoutSessionAsync(
	customerId: customerResult.Value.Id,
	priceId: cmd.PriceId,
	successUrl: cmd.SuccessUrl,
	cancelUrl: cmd.CancelUrl,
	ct);
	return sessionResult.IsSuccess
	? sessionResult.Value.Url
	: sessionResult.Error;

[Copilot]

INewsletterService.SubscribeAsync takes a SubscribeRequest object; there is no overload that accepts email, listId, and attributes as separate parameters. This example should construct new SubscribeRequest { Email = ..., ListIds = [...], Attributes = ... } and pass that into SubscribeAsync.

Suggested change

	email: cmd.Email,
	listId: cmd.ListId.ToString(),
	attributes: new Dictionary<string, object> { ["source"] = "checkout" },
	new SubscribeRequest
	{
	Email = cmd.Email,
	ListIds = [cmd.ListId.ToString()],
	Attributes = new Dictionary<string, object> { ["source"] = "checkout" }
	},

[Copilot]

CompletionRequest.Messages is a list of Message (with Role: MessageRole + Content) and there’s no new("user", ...) constructor. The sample should use Message.User(q.Text) (or new Message { Role = MessageRole.User, Content = ... }) so it compiles against Compendium.Abstractions.AI.

Suggested change

	Messages = [new("user", q.Text)],
	Messages = [Message.User(q.Text)],

[Copilot]

ServiceAccountKeyJson / ServiceAccountKeyPath are documented as supported auth inputs here, but they are not currently used by the adapter when acquiring access tokens (only PersonalAccessToken or ClientId/ClientSecret are used). The options table should reflect the real supported auth mechanisms to avoid misconfiguration.

[Copilot]

The usage snippet uses IIdentityProvider and CreateOrganizationAsync(cmd.Name, ct), but there is no IIdentityProvider abstraction in Compendium.Abstractions.Identity. The org API is IOrganizationService.CreateOrganizationAsync(CreateOrganizationRequest request, ...), so this sample won’t compile as written.

Suggested change

	public sealed class CreateTenantHandler(IIdentityProvider identity)
	: ICommandHandler<CreateTenantCommand, TenantId>
	{
	public async Task<Result<TenantId>> Handle(CreateTenantCommand cmd, CancellationToken ct)
	{
	var orgResult = await identity.CreateOrganizationAsync(cmd.Name, ct);
	public sealed class CreateTenantHandler(IOrganizationService organizations)
	: ICommandHandler<CreateTenantCommand, TenantId>
	{
	public async Task<Result<TenantId>> Handle(CreateTenantCommand cmd, CancellationToken ct)
	{
	var request = new CreateOrganizationRequest(cmd.Name);
	var orgResult = await organizations.CreateOrganizationAsync(request, ct);

[Copilot]

This says a service-account JSON key can be used for auth, but the current adapter token acquisition logic only supports PersonalAccessToken or OAuth ClientId/ClientSecret (the service-account key options are never read). Please adjust this auth guidance to match the implemented behavior (or implement SA key support).

[Copilot]

The usage snippet references ICacheStore, GetAsync<T>, and SetAsync, but there is no ICacheStore interface in this repo and the Redis adapter doesn’t ship those APIs. The example should be rewritten to use the actual Redis integration points (e.g., IIdempotencyStore / IProjectionCheckpointStore / IConnectionMultiplexer).

Suggested change

	public sealed class CachedOrderRepository(ICacheStore cache, IOrderRepository inner)
	: IOrderRepository
	{
	public async Task<Order?> FindAsync(OrderId id, CancellationToken ct)
	{
	var key = $"order:{id}";
	var cached = await cache.GetAsync<Order>(key, ct);
	if (cached is not null) return cached;
	var order = await inner.FindAsync(id, ct);
	if (order is not null)
	await cache.SetAsync(key, order, TimeSpan.FromMinutes(5), ct);
	using System.Text.Json;
	using StackExchange.Redis;
	public sealed class CachedOrderRepository(IConnectionMultiplexer redis, IOrderRepository inner)
	: IOrderRepository
	{
	public async Task<Order?> FindAsync(OrderId id, CancellationToken ct)
	{
	var db = redis.GetDatabase();
	var key = $"order:{id}";
	var cached = await db.StringGetAsync(key);
	if (cached.HasValue)
	return JsonSerializer.Deserialize<Order>(cached!);
	var order = await inner.FindAsync(id, ct);
	if (order is not null)
	{
	var payload = JsonSerializer.Serialize(order);
	await db.StringSetAsync(key, payload, TimeSpan.FromMinutes(5));
	}

[Copilot]

IEventStore does not have an AppendAsync method. The abstraction defines AppendEventsAsync(string aggregateId, IEnumerable<IDomainEvent> events, long expectedVersion, CancellationToken ct = default), so this sample won’t compile as written.

[Copilot]

This refers to migrations under tests/Integration/.../Database/, but there’s no such directory in the repo (tests use AutoCreateSchema / in-code CREATE TABLE IF NOT EXISTS instead). Please update the reference to point at a real schema bootstrap source (or remove it).

Suggested change

	For schema bootstrapping in a non-dev environment, run the migrations under `tests/Integration/.../Database/` as a reference, or write your own migrations.
	For schema bootstrapping in a non-dev environment, use the adapter's `AutoCreateSchema` / in-code `CREATE TABLE IF NOT EXISTS` behavior as a reference for the required tables, then create and manage your own version-controlled migrations.