add ai assist rules

.clinerules/ai-guidelines.md

@@ -0,0 +1,12 @@
+# Development Guidelines
+
+This directory contains guidelines for AI assistants:
+
+* [Cline AI Assistant Guidelines](cline-instructions.md) - Guidelines specific to using Cline AI assistant
+* [C# Development Guidelines](csharp-guidelines.md) - C# coding standards and best practices
+* [IdWeb Guidelines](idweb-guidelines.md) - Guidelines for working with IdWeb components and ecosystem
+
+The guidelines are split into separate files to organize different concerns:
+- Cline-specific capabilities and workflows
+- C# language-specific standards and practices
+- IdWeb-specific development guidelines and best practices

.clinerules/cline-instructions.md

@@ -0,0 +1,70 @@
+# Cline AI Assistant Guidelines
+
+## Core Principles
+
+* Make changes incrementally and verify each step
+* Always analyze existing code patterns before making changes
+* Prioritize built-in tools over shell commands
+* Follow existing project patterns and conventions
+* Maintain comprehensive test coverage
+
+## Tool Usage
+
+### File Operations
+* Use `read_file` for examining file contents instead of shell commands like `cat`
+* Use `replace_in_file` for targeted, specific changes to existing files
+* Use `write_to_file` only for new files or complete file rewrites
+* Use `list_files` to explore directory structures
+* Use `search_files` with precise regex patterns to find code patterns
+* Use `list_code_definition_names` to understand code structure before modifications
+
+### Command Execution
+* Use `execute_command` sparingly, preferring built-in file operation tools when possible
+* Always provide clear explanations for any executed commands
+* Set `requires_approval` to true for potentially impactful operations
+
+## Development Workflow
+
+### Planning Phase (PLAN MODE)
+* Begin complex tasks in PLAN mode to discuss approach
+* Analyze existing codebase patterns using search tools
+* Review related test files to understand testing patterns
+* Present clear implementation steps for approval
+* Ask clarifying questions early to avoid rework
+
+### Implementation Phase (ACT MODE)
+* Make changes incrementally, one file at a time
+* Verify each change before proceeding
+* Follow patterns discovered during planning phase
+* Focus on maintaining test coverage
+* Use error messages and linter feedback to guide fixes
+
+## Code Modifications
+
+### General Guidelines
+* Follow .editorconfig rules strictly
+* Preserve file headers and license information
+* Maintain consistent XML documentation
+* Respect existing error handling patterns
+* Keep line endings consistent with existing files
+
+### Quality Checks
+* Verify changes match existing code style
+* Ensure test coverage for new code
+* Validate changes against project conventions
+* Check for proper error handling
+* Maintain nullable reference type annotations
+
+## MCP Server Integration
+
+* Use appropriate MCP tools when available for specialized tasks
+* Access MCP resources efficiently using proper URIs
+* Handle MCP operation results appropriately
+* Follow server-specific authentication and usage patterns
+
+## Error Handling
+
+* Provide clear error messages and suggestions
+* Handle tool operation failures gracefully
+* Suggest alternative approaches when primary approach fails
+* Roll back changes if necessary to maintain stability

.clinerules/csharp-guidelines.md

@@ -0,0 +1,35 @@
+# C# Development Guidelines
+
+## General
+
+* Always use the latest version C#, currently C# 13 features
+* Never change global.json unless explicitly asked to
+* Never change package.json or package-lock.json files unless explicitly asked to
+* Never change NuGet.config files unless explicitly asked to
+
+## Formatting
+
+* Apply code-formatting style defined in `.editorconfig`
+* Prefer file-scoped namespace declarations and single-line using directives
+* Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`, `using`, `try`, etc.)
+* Ensure that the final return statement of a method is on its own line
+* Use pattern matching and switch expressions wherever possible
+* Use `nameof` instead of string literals when referring to member names
+* Ensure that XML doc comments are created for any public APIs. When applicable, include `<example>` and `<code>` documentation in the comments
+
+### Nullable Reference Types
+
+* Declare variables non-nullable, and check for `null` at entry points
+* Always use `is null` or `is not null` instead of `== null` or `!= null`
+* Trust the C# null annotations and don't add null checks when the type system says a value cannot be null
+
+### Testing
+
+* We use xUnit SDK v2 for tests
+* Emit "Act", "Arrange" or "Assert" comments
+* Use Moq 4.14.x for mocking in tests
+* Copy existing style in nearby files for test method names and capitalization
+
+## Running tests
+
+* To build and run tests in the repo, run `dotnet test`, you need one solution open, or specify the solution

.clinerules/idweb-guidelines.md

@@ -0,0 +1,95 @@
+# IdWeb Guidelines
+
+## Overview
+
+Microsoft Identity Web is a comprehensive authentication and authorization library for ASP.NET Core applications that integrates with the Microsoft identity platform and Azure AD B2C. The library provides essential functionality for:
+
+- Web applications that sign in users and optionally call web APIs
+- Protected web APIs that may call downstream web APIs
+- Token cache implementations
+- Microsoft Graph integration
+- Azure SDK integration
+
+Through its modular architecture and extensive features, Microsoft Identity Web simplifies the implementation of identity and access management in modern web applications while maintaining security best practices.
+
+## Repository Structure
+
+### Core Directories
+- `/src` - Contains all source code for the Microsoft.Identity.Web packages
+- `/tests` - Contains all test projects including unit tests, integration tests and E2E tests
+- `/benchmark` - Performance benchmarking tests
+- `/build` - Build scripts and configuration
+- `/docs` - Documentation and blog posts
+- `/ProjectTemplates` - Project templates for various ASP.NET Core scenarios
+- `/tools` - Development and configuration tools
+
+### Project Templates
+The following templates are provided:
+- Blazor Server Web Applications
+- Blazor WebAssembly Applications
+- Azure Functions
+- Razor Pages Web Applications
+- ASP.NET Core MVC (Starter Web)
+- ASP.NET Core Web API
+- Worker Service
+
+## Shipped DLLs/Packages
+
+The following NuGet packages are shipped as part of Microsoft.Identity.Web:
+
+### Core Packages
+- Microsoft.Identity.Web - Core authentication and authorization functionality
+- Microsoft.Identity.Web.UI - UI components and controllers for authentication
+- Microsoft.Identity.Web.TokenCache - Token cache implementations
+- Microsoft.Identity.Web.TokenAcquisition - Token acquisition functionality
+
+### Integration Packages
+- Microsoft.Identity.Web.Azure - Azure SDK integration support
+- Microsoft.Identity.Web.Certificate - Certificate management and loading
+- Microsoft.Identity.Web.Certificateless - Support for certificateless authentication
+- Microsoft.Identity.Web.DownstreamApi - Support for calling downstream APIs
+- Microsoft.Identity.Web.OWIN - OWIN middleware integration
+
+### Microsoft Graph Packages
+- Microsoft.Identity.Web.MicrosoftGraph - Microsoft Graph integration
+- Microsoft.Identity.Web.MicrosoftGraphBeta - Microsoft Graph Beta API integration
+- Microsoft.Identity.Web.GraphServiceClient - Graph SDK integration
+- Microsoft.Identity.Web.GraphServiceClientBeta - Graph Beta SDK integration
+
+### Additional Functionality
+- Microsoft.Identity.Web.Diagnostics - Diagnostic and logging support
+- Microsoft.Identity.Web.OidcFIC - OpenID Connect Federated Identity Credential support
+
+## Development Guidelines
+
+### Common Development Patterns
+- Follow .editorconfig rules strictly
+- Ensure proper error handling
+- Maintain test coverage for changes
+- Document API changes thoroughly
+- Keep configuration consistent with project standards
+
+### Testing Requirements
+- Include tests for all code changes
+- Follow existing test patterns
+- Include benchmark tests for performance-sensitive changes
+- Verify security implications of changes
+
+### Public API Changes
+- The project uses Microsoft.CodeAnalysis.PublicApiAnalyzers (version 3.3.4) to track changes to public APIs
+- For any changes to public APIs (classes, interfaces, methods, properties, etc.), you must:
+  1. Locate the PublicAPI.Unshipped.txt file in the directory of the changed code
+  2. Include the complete API signature
+
+Example format:
+```diff
+// Adding new API
++MyNamespace.MyClass.MyNewMethod() -> void
++MyNamespace.MyClass.MyProperty.get -> string
++MyNamespace.MyClass.MyProperty.set -> void
+
+// Removing API
+-MyNamespace.MyClass.OldMethod() -> void
+```
+
+The analyzer will verify during build that all public API changes are properly documented, and the build will fail if changes are not reflected in PublicAPI.Unshipped.txt.

.github/copilot-instructions.md

@@ -0,0 +1 @@
+Carefully review all markdown documents in the ../.clinerules folder. Those are your custom instructions.