@tenantegroup/ai-rules-mcp 1.0.0

package/rules/cloudflare/workflows.md

@@ -0,0 +1,593 @@
+# Cloudflare Workflows
+
+## Core Principle
+Workflows enable durable, multi-step orchestration with automatic retry, state persistence, and saga-pattern rollback support. Use Workflows for any operation that requires:
+- Coordinating multiple steps across external systems
+- Long-running operations (minutes to weeks)
+- Automatic recovery from failures with state persistence
+- Semantic reversal of operations on failure (saga pattern)
+- Human-in-the-loop approvals or event-driven pauses
+
+## When to Use Workflows
+
+### Use Workflows For
+- **Multi-step transactions** — Fund transfers, payment processing, order fulfillment that span external systems (banks, payment processors, inventory systems)
+- **Long-running orchestration** — Data pipelines, image processing, AI-powered workflows lasting hours or days
+- **Event-driven workflows** — Wait for approvals, user input, webhook responses, or external system callbacks before proceeding
+- **State-machine logic** — Complex workflows with multiple paths, retries, and compensating actions
+- **User lifecycle automation** — Onboarding, trial expirations, automated emails with pauses and external event dependencies
+- **Human-in-the-loop systems** — Pause workflows for approval, resume programmatically after decision
+
+### Do NOT Use Workflows For
+- Simple fire-and-forget async tasks (use **Queues** instead)
+- Stateless, millisecond-scale operations (use **Workers** instead)
+- Real-time collaboration requiring coordinated client state (use **Durable Objects** instead)
+- Pure caching or session storage (use **KV** instead)
+
+## Workflow Architecture
+
+### Durable Steps (`step.do()`)
+
+Every step in a Workflow is durable — execution is logged, state is persisted, and retries are automatic:
+
+```typescript
+export class ProcessPaymentWorkflow extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, step: WorkflowStep) {
+    // Step 1: Charge the card
+    const charge = await step.do("charge-card", async () => {
+      return await this.env.PAYMENT.charge({
+        amount: event.payload.amount,
+        cardToken: event.payload.token,
+        idempotencyKey: `${event.payload.orderId}:charge`,
+      });
+    });
+
+    // Step 2: Update inventory (fails if charge succeeds but this fails)
+    const inventory = await step.do("deduct-inventory", async () => {
+      return await this.env.DB.prepare(
+        "UPDATE products SET stock = stock - 1 WHERE id = ?"
+      ).bind(event.payload.productId).first();
+    });
+
+    // Step 3: Send confirmation
+    await step.do("send-email", async () => {
+      await this.env.MAILER.send({
+        to: event.payload.email,
+        subject: "Order Confirmation",
+        body: "Your order has been confirmed",
+      });
+    });
+  }
+}
+```
+
+**Key Properties:**
+- Each `step.do()` is uniquely named (name is the identifier)
+- Step body executes exactly once; output is memoized
+- Retries are automatic on transient failures
+- If a step fails after maximum retries, the Workflow fails
+
+### Saga Pattern Rollbacks
+
+The **saga pattern** defines a compensating action for each step. If a Workflow fails, rollback handlers execute in **reverse order** (LIFO), undoing completed steps.
+
+#### Without Rollbacks (Manual Compensation)
+```typescript
+let chargeId;
+let inventoryDeducted = false;
+
+try {
+  chargeId = await step.do("charge-card", async () => {
+    return await this.env.PAYMENT.charge(...);
+  });
+  
+  inventoryDeducted = await step.do("deduct-inventory", async () => {
+    return await this.env.DB.prepare(...).first();
+  });
+  
+  // If email fails, manual cleanup outside steps
+  await step.do("send-email", async () => {
+    // Fails here — how do we undo inventory?
+    throw new Error("Email service down");
+  });
+} catch (error) {
+  // Manual unwinding — brittle, error-prone, easy to forget steps
+  if (inventoryDeducted) {
+    await step.do("undo-inventory", async () => {
+      return await this.env.DB.prepare(
+        "UPDATE products SET stock = stock + 1 WHERE id = ?"
+      ).bind(event.payload.productId).first();
+    });
+  }
+  if (chargeId) {
+    await step.do("refund-charge", async () => {
+      return await this.env.PAYMENT.refund({
+        chargeId,
+        idempotencyKey: `${event.payload.orderId}:refund`,
+      });
+    });
+  }
+  throw error;
+}
+```
+
+#### With Rollbacks (Built-In Compensation)
+```typescript
+export class ProcessPaymentWorkflow extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, step: WorkflowStep) {
+    // Charge card — if needed, refund
+    const charge = await step.do(
+      "charge-card",
+      async () => {
+        return await this.env.PAYMENT.charge({
+          amount: event.payload.amount,
+          cardToken: event.payload.token,
+          idempotencyKey: `${event.payload.orderId}:charge`,
+        });
+      },
+      {
+        rollback: async ({ output }) => {
+          // output is the charge object returned from step.do()
+          if (output && output.id) {
+            await this.env.PAYMENT.refund({
+              chargeId: output.id,
+              idempotencyKey: `${event.payload.orderId}:rollback-charge`,
+            });
+          }
+        },
+      }
+    );
+
+    // Deduct inventory — if needed, restock
+    const inventory = await step.do(
+      "deduct-inventory",
+      async () => {
+        return await this.env.DB.prepare(
+          "UPDATE products SET stock = stock - 1 WHERE id = ? RETURNING *"
+        ).bind(event.payload.productId).first();
+      },
+      {
+        rollback: async ({ output }) => {
+          // Restock inventory (must be idempotent)
+          await this.env.DB.prepare(
+            "UPDATE products SET stock = stock + 1 WHERE id = ?"
+          ).bind(event.payload.productId).run();
+        },
+      }
+    );
+
+    // Send confirmation (no rollback needed — email is idempotent)
+    await step.do("send-email", async () => {
+      await this.env.MAILER.send({
+        to: event.payload.email,
+        subject: "Order Confirmation",
+        body: "Your order has been confirmed",
+      });
+    });
+  }
+}
+```
+
+**Rollback Rules:**
+1. **Rollback handlers execute in reverse LIFO order** — If steps A → B → C run, and C fails, rollbacks run C → B → A
+2. **Only failed Workflows trigger rollback** — If user code catches an error and Workflow continues, no rollback. Rollback only starts when Workflow is about to fail terminally
+3. **Failed steps CAN still rollback** — A step that fails may have partially succeeded (e.g., charge captured but transient error before returning). Rollback handlers receive `output`, but must handle `output === undefined`
+4. **Rollback handlers MUST be idempotent** — Design as if they will be called multiple times. Use idempotency keys for all external operations:
+   ```typescript
+   // Refund with idempotency key — safe to retry
+   await this.env.PAYMENT.refund({
+     chargeId: output.id,
+     idempotencyKey: `${orderId}:rollback-charge`,  // ← Same key on retry
+   });
+   ```
+
+## State Persistence & Long-Running Workflows
+
+Workflows persist state across the entire execution, even if the Worker isolate is recycled:
+
+```typescript
+export class DataProcessingWorkflow extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, step: WorkflowStep) {
+    // Pause workflow for 7 days (state is persisted)
+    await step.sleep("wait-7-days", "7 days");
+
+    // Process data
+    const result = await step.do("process-data", async () => {
+      return await expensiveProcessing(event.payload);
+    });
+
+    // Pause for user approval (wait for external event)
+    const approval = await step.waitForEvent("await-approval", {
+      event: "user-approved",
+      timeout: "24 hours",
+    });
+
+    if (approval.data.approved) {
+      await step.do("publish", async () => {
+        await this.env.STORAGE.put(`published/${event.payload.id}`, result);
+      });
+    }
+  }
+}
+```
+
+**Key Features:**
+- **`step.sleep(name, duration)`** — Pause for seconds, hours, days, weeks
+- **`step.sleepUntil(name, timestamp)`** — Resume at specific ISO timestamp
+- **`step.waitForEvent(name, options)`** — Pause until external event (webhook, API call)
+- **State is persisted across pauses** — Isolate recycling, server shutdown, etc. do not affect execution
+- **Timeouts prevent forever-waiting** — `waitForEvent()` supports `timeout` to terminate if event never arrives
+
+## Workflow Lifecycle Management
+
+### Triggering Workflows
+
+```typescript
+// From a Worker/API endpoint, trigger a new Workflow instance
+export default {
+  async fetch(request, env) {
+    const workflowId = crypto.randomUUID();
+
+    await env.WORKFLOWS.create(ProcessPaymentWorkflow, {
+      id: workflowId,
+      params: {
+        orderId: "order-123",
+        amount: 9999,
+        email: "user@example.com",
+      },
+    });
+
+    return new Response(
+      JSON.stringify({ workflowId, status: "created" }),
+      { status: 202 }
+    );
+  },
+};
+```
+
+### Pausing & Resuming Workflows
+
+```typescript
+// Pause a running Workflow
+await env.WORKFLOWS.pause(workflowId);
+
+// Resume a paused Workflow
+await env.WORKFLOWS.resume(workflowId);
+
+// Terminate a Workflow
+await env.WORKFLOWS.terminate(workflowId);
+```
+
+### Querying Workflow Status
+
+```typescript
+// Get current Workflow status (used for polling or dashboard)
+const status = await env.WORKFLOWS.getStatus(workflowId);
+// Returns: { id, status, steps, history, nextScheduledTime, output, error }
+```
+
+## Configuration & Binding
+
+### wrangler.toml
+
+Workflows do NOT require explicit binding; they are built-in to the Workers runtime:
+
+```toml
+# wrangler.toml
+name = "my-app"
+main = "src/index.ts"
+
+[[workflows]]
+binding = "WORKFLOWS"
+name = "my_workflows"
+
+# Bind the workflow class
+[[env.production.workflows]]
+binding = "WORKFLOWS"
+class = "ProcessPaymentWorkflow"
+```
+
+### Database Access from Workflows
+
+Workflows can access D1, KV, and other Cloudflare bindings the same way Workers do:
+
+```typescript
+export class UserOnboardingWorkflow extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, step: WorkflowStep) {
+    const user = await step.do("fetch-user", async () => {
+      return await this.env.DB.prepare(
+        "SELECT * FROM users WHERE id = ?"
+      ).bind(event.payload.userId).first();
+    });
+
+    // Send welcome email
+    await step.do("send-welcome-email", async () => {
+      await this.env.MAILER.send({
+        to: user.email,
+        subject: "Welcome!",
+        body: `Hi ${user.name}`,
+      });
+    });
+
+    // Set trial expiration (14 days from now)
+    await step.sleep("wait-trial", "14 days");
+
+    // Check if user has converted
+    const hasConverted = await step.do("check-conversion", async () => {
+      const subscription = await this.env.DB.prepare(
+        "SELECT * FROM subscriptions WHERE user_id = ? AND status = 'active'"
+      ).bind(event.payload.userId).first();
+      return !!subscription;
+    });
+
+    if (!hasConverted) {
+      // Send expiration notice
+      await step.do("send-expiration-email", async () => {
+        await this.env.MAILER.send({
+          to: user.email,
+          subject: "Your trial has ended",
+          body: "Subscribe now to continue",
+        });
+      });
+    }
+  }
+}
+```
+
+## Error Handling & Observability
+
+### Retry Behavior
+
+Workflows automatically retry failed steps with exponential backoff:
+- Default max retries: 5 (configurable)
+- Backoff: exponential with jitter
+- If a step exceeds max retries, the Workflow fails and rollback begins
+
+### Logging from Workflows
+
+```typescript
+export class OrderWorkflow extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, step: WorkflowStep) {
+    // Use console for structured logging (same as Workers)
+    console.log(JSON.stringify({
+      event: "workflow_start",
+      workflowId: event.id,
+      orderId: event.payload.orderId,
+      timestamp: new Date().toISOString(),
+    }));
+
+    const charge = await step.do("charge", async () => {
+      const result = await this.env.PAYMENT.charge({...});
+      console.log(JSON.stringify({
+        event: "charge_success",
+        chargeId: result.id,
+        amount: result.amount,
+      }));
+      return result;
+    });
+  }
+}
+```
+
+### Debugging in Dashboard
+
+- **Cloudflare Dashboard** → **Workflows** → View step-by-step execution history
+- See input/output for each step
+- View retry attempts and timing
+- Inspect rollback execution order
+
+## Idempotency & Distributed Systems
+
+### Critical: External Idempotency Keys
+
+Since steps can be retried, **all external operations MUST use idempotency keys** to prevent duplicate side effects:
+
+```typescript
+// ❌ NOT IDEMPOTENT — repeated calls charge multiple times
+await this.env.PAYMENT.charge({
+  amount: 9999,
+  card: token,
+  // No idempotency key — if Workflow retries, user charged twice
+});
+
+// ✅ IDEMPOTENT — repeated calls use same key, provider deduplicates
+await this.env.PAYMENT.charge({
+  amount: 9999,
+  card: token,
+  idempotencyKey: `${orderId}:charge:attempt1`,
+});
+```
+
+### D1 Transactions
+
+For D1 operations, use Drizzle transactions to ensure atomic steps:
+
+```typescript
+const result = await step.do("create-order", async () => {
+  return await this.env.DB.transaction(async (tx) => {
+    const order = await tx.insert(ordersTable).values({
+      id: event.payload.orderId,
+      amount: event.payload.amount,
+      status: "pending",
+    }).returning();
+
+    await tx.insert(orderItemsTable).values(
+      event.payload.items.map((item) => ({
+        orderId: order[0].id,
+        productId: item.productId,
+        quantity: item.quantity,
+      }))
+    );
+
+    return order[0];
+  });
+});
+```
+
+## Deployment & Versioning
+
+### Deploy Workflows with Wrangler
+
+```bash
+# Deploy to production
+wrangler deploy
+
+# Deploy to staging
+wrangler deploy --env staging
+```
+
+Workflows are versioned with your application code. If you deploy a new Workflow definition:
+- New instances use the new definition
+- Running instances continue with the old definition (no breaking mid-flight)
+- After deploying, new workflow IDs reference the new version
+
+### Updating Running Workflows
+
+Avoid changing Workflow definitions while instances are running:
+
+```typescript
+// ❌ RISKY — Modifying a running Workflow can cause inconsistency
+export class OrderWorkflow extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, step: WorkflowStep) {
+    // Previously: step 1 was "charge"
+    // Now: renamed to "charge-card"
+    // Running instances fail because state history expects "charge"
+    await step.do("charge-card", ...);  // ← Causes desynchronization
+  }
+}
+
+// ✅ SAFE — Create new version, let old instances finish
+export class OrderWorkflowV2 extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, step: WorkflowStep) {
+    // New Workflow class, old instances unaffected
+    await step.do("charge-card", ...);
+  }
+}
+```
+
+Best practice: Trigger new instances to use `OrderWorkflowV2`, and let old `OrderWorkflow` instances complete.
+
+## Best Practices
+
+### 1. Keep Steps Focused
+- One step = one logical operation
+- Avoid grouping multiple external calls in a single step
+```typescript
+// ❌ TOO BROAD
+await step.do("process-order", async () => {
+  const charge = await this.env.PAYMENT.charge(...);
+  const inventory = await this.env.DB.updateInventory(...);
+  const email = await this.env.MAILER.send(...);
+  return { charge, inventory, email };
+});
+
+// ✅ FOCUSED
+await step.do("charge", async () => {
+  return await this.env.PAYMENT.charge(...);
+});
+await step.do("deduct-inventory", async () => {
+  return await this.env.DB.updateInventory(...);
+});
+await step.do("send-email", async () => {
+  return await this.env.MAILER.send(...);
+});
+```
+
+### 2. Always Provide Rollback for External State Changes
+```typescript
+// ✅ Fund transfer with rollback
+await step.do(
+  "debit-source",
+  () => bankA.debit(from, amount),
+  {
+    rollback: async ({ output }) => {
+      bankA.credit(from, amount, output.id);
+    },
+  }
+);
+```
+
+### 3. Use Timeouts on External Waits
+```typescript
+// ✅ Wait for approval with timeout
+const approval = await step.waitForEvent("approval", {
+  event: "user-approved",
+  timeout: "24 hours",  // Fail if no approval within 24 hours
+});
+```
+
+### 4. Implement Application-Level Idempotency Checks
+```typescript
+// ✅ Check if order already exists before creating
+const existing = await step.do("check-existing", async () => {
+  return await this.env.DB.prepare(
+    "SELECT id FROM orders WHERE id = ?"
+  ).bind(event.payload.orderId).first();
+});
+
+if (existing) {
+  console.log("Order already processed");
+  return { status: "already_completed", orderId: existing.id };
+}
+
+// Proceed with creation
+await step.do("create-order", async () => {
+  return await this.env.DB.prepare(
+    "INSERT INTO orders (id, ...) VALUES (?, ...)"
+  ).bind(event.payload.orderId, ...).run();
+});
+```
+
+### 5. Monitor Workflow Metrics
+- Track execution time per step
+- Monitor rollback frequency
+- Alert on max retries exceeded
+- Log all external API calls with timing and status
+
+### 6. Design for Long Pauses
+```typescript
+// ✅ Designed for week-long pause
+export class TrialExpirationWorkflow extends WorkflowEntrypoint {
+  async run(event: WorkflowEvent, step: WorkflowStep) {
+    // Pause for entire trial period
+    await step.sleep("trial-period", "14 days");
+
+    // Check conversion status
+    const converted = await step.do("check-conversion", async () => {
+      const sub = await this.env.DB.prepare(
+        "SELECT * FROM subscriptions WHERE user_id = ?"
+      ).bind(event.payload.userId).first();
+      return !!sub?.activeUntil;
+    });
+
+    // Send appropriate email based on conversion
+    await step.do("notify", async () => {
+      if (converted) {
+        // Already subscribed — send nothing
+        return;
+      }
+      // Trial ended — send upgrade email
+      await this.env.MAILER.send({...});
+    });
+  }
+}
+```
+
+## When to Choose Between Workflows, Queues, and Durable Objects
+
+| Feature | Workflows | Queues | Durable Objects |
+|---------|-----------|--------|-----------------|
+| **Multi-step orchestration** | ✅ Native | ⚠️ Manual | ❌ Not designed for |
+| **Long-running (hours/days)** | ✅ Yes | ❌ ~15 min limit | ✅ Yes, but stateless |
+| **State persistence** | ✅ Yes | ❌ No | ✅ Yes, but in-memory |
+| **Automatic retries** | ✅ Yes | ✅ Yes | ❌ No |
+| **Saga pattern rollback** | ✅ Yes (native) | ❌ Manual | ❌ Not applicable |
+| **Wait for external events** | ✅ Yes | ❌ No | ❌ No |
+| **Cost per operation** | Low (pay per step) | Low (pay per message) | High (compute-intensive) |
+| **Use case** | Orchestration, transactions, approvals | Simple async tasks, email | Realtime coordination, chat |
+
+**Decision Tree:**
+- Need to orchestrate multiple external systems? → **Workflows**
+- Need simple fire-and-forget async tasks? → **Queues**
+- Need coordinated state across multiple clients? → **Durable Objects**
+- Otherwise → Use **Workers** directly

package/rules/dotnet/api.md

@@ -0,0 +1,26 @@
+Rule: Enforce API Integration with Refit
+Requirements:
+- AI MUST follow all `.ai/rules/*.md` files and prioritize architecture constraints.
+- AI MUST use Refit interfaces for HTTP API contracts.
+- AI MUST use strongly typed DTOs for requests and responses.
+- AI MUST wrap Refit interfaces in service classes before ViewModel consumption.
+- AI MUST configure authenticated requests via DelegatingHandler.
+- AI MUST set request timeout to 30 seconds unless feature-specific override is required.
+- AI MUST implement retry policy: 3 retries with exponential backoff (250ms, 500ms, 1000ms) for transient network failures and HTTP 5xx only.
+- AI MUST map API DTOs into domain/data models before persistence or UI use.
+- AI MUST persist API results to SQLite before UI reads where offline-first applies.
+- AI MUST handle `ApiException` and surface safe errors.
+Prohibited:
+- AI MUST NOT call Refit interfaces directly from Views or ViewModels.
+- AI MUST NOT use raw `HttpClient` for standard API integration.
+- AI MUST NOT log auth headers, tokens, passwords, or secret payload fields.
+- AI MUST NOT use dynamic/weakly typed API payload handling.
+- AI MUST NOT bypass retry/error handling constraints.
+Patterns:
+- `public interface IUserApi { [Get("/users/me")] Task<UserDto> GetCurrentUserAsync(); }`
+- `UserApiService` depends on `IUserApi`.
+- Authentication handler injects bearer token from secure secret provider.
+- Service flow: Refit call -> DTO mapping -> repository save -> ViewModel read.
+Examples:
+- `builder.Services.AddRefitClient<IUserApi>().ConfigureHttpClient(c => c.BaseAddress = new Uri(baseUrl));`
+- `catch (ApiException ex) { ... }`

package/rules/dotnet/architecture.md

@@ -0,0 +1,27 @@
+Rule: Enforce Application Architecture
+Requirements:
+- AI MUST follow this file and all `.ai/rules/*.md` files before generating any code.
+- AI MUST prioritize these rules over default generation behavior.
+- AI MUST use .NET MAUI with MVVM via CommunityToolkit.Mvvm.
+- AI MUST keep strict separation: Views = UI only, ViewModels = state/commands only, Services = business logic.
+- AI MUST use XAML-first UI and MAUI Shell URI routing.
+- AI MUST use dependency injection for all dependencies.
+- AI MUST register dependencies only in composition root files (`MauiProgram.cs` or `Program.cs`).
+- AI MUST register services through interfaces.
+- AI MUST register ViewModels as transient by default; singleton usage requires explicit justification.
+- AI MUST place business logic in services only.
+- AI MUST route data flow as API -> SQLite -> Service -> ViewModel -> View.
+Prohibited:
+- AI MUST NOT bypass these architecture constraints.
+- AI MUST NOT invent alternative architectures, patterns, or folder models.
+- AI MUST NOT place business logic in Views, code-behind, or ViewModels.
+- AI MUST NOT call APIs or SQLite directly from Views or ViewModels.
+- AI MUST NOT instantiate services with `new` outside composition root.
+Patterns:
+- Register dependencies in `MauiProgram.cs` or `Program.cs` only.
+- Use constructor injection only.
+- Use `InitializeAsync()` for runtime initialization.
+- Keep feature modules self-contained under `Features/<FeatureName>/`.
+Examples:
+- `builder.Services.AddSingleton<IAuthService, AuthService>();`
+- `await Shell.Current.GoToAsync("//dashboard");`

package/rules/dotnet/cli.md

@@ -0,0 +1,26 @@
+Rule: Enforce CLI and Console Standards
+Requirements:
+- AI MUST follow all `.ai/rules/*.md` files when generating CLI code.
+- AI MUST use Spectre.Console and Spectre.Console.Cli for CLI applications.
+- AI MUST implement command handlers as command classes.
+- AI MUST define arguments/options via `CommandSettings` classes.
+- AI MUST register commands through `CommandApp` configuration.
+- AI MUST use dependency injection for services and command dependencies.
+- AI MUST return deterministic exit codes (`0` success, `1` runtime error, `2` invalid arguments, `3` configuration error).
+- AI MUST support `--help` and `--version`.
+- AI MUST use async command execution for I/O operations.
+- AI MUST apply centralized logging with Serilog.
+Prohibited:
+- AI MUST NOT parse command-line args manually.
+- AI MUST NOT instantiate services directly inside commands.
+- AI MUST NOT use blocking synchronous I/O in command execution paths.
+- AI MUST NOT use inconsistent command naming conventions.
+- AI MUST NOT rely on interactive prompts for automation-only command paths.
+Patterns:
+- `public sealed class SyncCommand : AsyncCommand<SyncSettings>`
+- `app.Configure(c => c.AddCommand<SyncCommand>("sync"));`
+- `SyncCommand` depends on `ISyncService` via constructor injection.
+- Output uses `AnsiConsole` rendering primitives.
+Examples:
+- `return 2; // invalid args`
+- `await _syncService.RunAsync(cancellationToken);`

package/rules/dotnet/configuration.md

@@ -0,0 +1,26 @@
+Rule: Enforce Configuration and Secrets
+Requirements:
+- AI MUST follow all `.ai/rules/*.md` files for configuration and secret handling.
+- AI MUST store non-sensitive settings in `appsettings.json`.
+- AI MUST support environment-specific overrides (`appsettings.Development.json`, `appsettings.Production.json`).
+- AI MUST centralize config access through a typed configuration service.
+- AI MUST load and validate required configuration at startup (fail fast on missing required values).
+- AI MUST store secrets in platform secure storage only.
+- AI MUST use a dedicated secrets service abstraction.
+- AI MUST inject configuration and secrets services via DI.
+- AI MUST use strongly typed option models where applicable.
+- AI MUST keep runtime configuration immutable after startup load unless explicitly designed for reload.
+Prohibited:
+- AI MUST NOT store secrets in `appsettings*.json`.
+- AI MUST NOT commit secrets, credentials, or tokens to source control.
+- AI MUST NOT access configuration via scattered magic-string lookups.
+- AI MUST NOT log secret configuration values.
+- AI MUST NOT bypass startup validation of required settings.
+Patterns:
+- `Configuration/AppConfigurationService.cs`
+- `Configuration/SecretsService.cs`
+- `builder.Configuration.AddJsonFile("appsettings.json", optional: false, reloadOnChange: false);`
+- Bind and validate options at startup.
+Examples:
+- `public string ApiBaseUrl => _config["Api:BaseUrl"]!;`
+- `await SecureStorage.SetAsync("AuthToken", token);`