aauth-dev · dasiths · Sep 10, 2026 · Sep 10, 2026
diff --git a/.agent/plans/2026-05-27-ap-enrollment-key-naming/implementation-plan.md b/.agent/plans/2026-05-27-ap-enrollment-key-naming/implementation-plan.md
@@ -1,8 +1,4 @@
----
-title: "AP Enrollment Key Naming — Implementation Plan"
-description: Rename EnrolledKeyId to LocalKeyHandle, default to JWK thumbprint, and clarify docs/samples around AP↔agent identifier separation.
-ms.date: 2026-05-27
----
+# AP Enrollment Key Naming — Implementation Plan
 
 ## Goals
 

diff --git a/.agent/plans/2026-05-27-ap-enrollment-key-naming/research.md b/.agent/plans/2026-05-27-ap-enrollment-key-naming/research.md
@@ -1,8 +1,4 @@
----
-title: "AP Enrollment Key Naming — Research"
-description: Spec alignment review of how the SDK names and uses the durable key identifier produced by Agent Provider enrollment, and how it flows into refresh.
-ms.date: 2026-05-27
----
+# AP Enrollment Key Naming — Research
 
 ## Problem Statement
 

diff --git a/.agent/plans/2026-05-27-token-refresher-concrete-types/implementation-plan.md b/.agent/plans/2026-05-27-token-refresher-concrete-types/implementation-plan.md
@@ -1,8 +1,4 @@
----
-title: "ITokenRefresher Concrete Types — Implementation Plan"
-description: Phased plan for adding AgentProviderTokenRefresher and SelfIssuedTokenRefresher to the SDK
-ms.date: 2026-05-27
----
+# ITokenRefresher Concrete Types — Implementation Plan
 
 ## Phase 1: Add `AgentProviderTokenRefresher`
 

diff --git a/.agent/plans/2026-05-27-token-refresher-concrete-types/research.md b/.agent/plans/2026-05-27-token-refresher-concrete-types/research.md
@@ -1,8 +1,4 @@
----
-title: "ITokenRefresher Concrete Types — Research"
-description: Research document for introducing built-in ITokenRefresher implementations to the AAuth SDK
-ms.date: 2026-05-27
----
+# ITokenRefresher Concrete Types — Research
 
 ## Problem Statement
 

diff --git a/.agent/plans/2026-05-28-self-issued-client-builder-shorthand/.plan-log.md b/.agent/plans/2026-05-28-self-issued-client-builder-shorthand/.plan-log.md
@@ -1,7 +1,4 @@
----
-title: "Self-Issued Client Builder Shorthand — Planning Log"
-ms.date: 2026-05-28
----
+# Self-Issued Client Builder Shorthand — Planning Log
 
 ## Status: ALL PHASES COMPLETE
 

diff --git a/...t/plans/2026-05-28-self-issued-client-builder-shorthand/before-after-summary.md b/...t/plans/2026-05-28-self-issued-client-builder-shorthand/before-after-summary.md
@@ -1,8 +1,4 @@
----
-title: "Before / After — Fluent API Migration Summary"
-description: Side-by-side comparison of old vs new API patterns and affected files
-ms.date: 2026-05-28
----
+# Before / After — Fluent API Migration Summary
 
 ## Self-Issued Identity (Phases 1 + 5)
 

diff --git a/...nt/plans/2026-05-28-self-issued-client-builder-shorthand/implementation-plan.md b/...nt/plans/2026-05-28-self-issued-client-builder-shorthand/implementation-plan.md
@@ -1,8 +1,4 @@
----
-title: "Client Builder Fluent Shorthand — Implementation Plan"
-description: Phased plan for fluent shorthand methods across the AAuth SDK builder surface
-ms.date: 2026-05-28
----
+# Client Builder Fluent Shorthand — Implementation Plan
 
 > **Phases 1–4:** COMPLETE (self-issued shorthand)
 > **Phases 5–10:** COMPLETE (fluent refactor + AP-enrolled + resource shorthand + constants/extensions + response helpers)

diff --git a/.agent/plans/2026-05-28-self-issued-client-builder-shorthand/research.md b/.agent/plans/2026-05-28-self-issued-client-builder-shorthand/research.md
@@ -1,8 +1,4 @@
----
-title: "Self-Issued Client Builder Shorthand — Research"
-description: Research for combining AgentTokenBuilder into the AAuthClientBuilder fluent API
-ms.date: 2026-05-28
----
+# Self-Issued Client Builder Shorthand — Research
 
 ## Problem Statement
 

diff --git a/.agent/plans/2026-06-03-sdk-namespace-hygiene/implementation-plan.md b/.agent/plans/2026-06-03-sdk-namespace-hygiene/implementation-plan.md
@@ -1,8 +1,4 @@
----
-title: "SDK Namespace Hygiene — Implementation Plan"
-description: Phased plan to improve AAuth SDK namespace layout and public type naming
-ms.date: 2026-06-03
----
+# SDK Namespace Hygiene — Implementation Plan
 
 This plan addresses the four issues in [research.md](research.md). Phasing is
 **non-breaking first**: Phase 1 ships the high-value DI ergonomics win on its

diff --git a/.agent/plans/2026-06-03-sdk-namespace-hygiene/research.md b/.agent/plans/2026-06-03-sdk-namespace-hygiene/research.md
@@ -1,8 +1,4 @@
----
-title: "SDK Namespace Hygiene — Research"
-description: Research document for improving the AAuth SDK namespace layout and public type naming
-ms.date: 2026-06-03
----
+# SDK Namespace Hygiene — Research
 
 ## Problem Statement
 

diff --git a/.agent/plans/2026-09-08-aauth-v10-spec-migration/api-surface-map.md b/.agent/plans/2026-09-08-aauth-v10-spec-migration/api-surface-map.md
@@ -1,7 +1,3 @@
----
-description: Complete migration public API inventory and reviewed ownership, defaults and verification.
----
-
 # Public API surface map
 
 Phase 11, 2026-09-09. Implementation baseline: `ba768f1`. This is the complete migration source inventory,

diff --git a/.agent/plans/2026-09-08-aauth-v10-spec-migration/capability-scenarios.md b/.agent/plans/2026-09-08-aauth-v10-spec-migration/capability-scenarios.md
@@ -1,7 +1,3 @@
----
-description: Phase 12 migration capability coverage, runnable scenarios and explicit evidence limits.
----
-
 # Capability Scenarios
 
 Baseline: ba768f1. Cross-checked against [api-surface-map.md](api-surface-map.md),

diff --git a/.agent/plans/2026-09-08-aauth-v10-spec-migration/conformance-ledger.md b/.agent/plans/2026-09-08-aauth-v10-spec-migration/conformance-ledger.md
@@ -1,7 +1,3 @@
----
-description: Section-oriented v10 conformance evidence and explicit implementation, optional and deployment dispositions.
----
-
 # Conformance Ledger
 
 ## Final Status

diff --git a/.agent/plans/2026-09-08-aauth-v10-spec-migration/docs-surface-map.md b/.agent/plans/2026-09-08-aauth-v10-spec-migration/docs-surface-map.md
diff --git a/.agent/plans/2026-09-08-aauth-v10-spec-migration/implementation-log.md b/.agent/plans/2026-09-08-aauth-v10-spec-migration/implementation-log.md
@@ -1,7 +1,3 @@
----
-description: Decisions and validation results for the AAuth v10 migration.
----
-
 # Implementation Log - AAuth v10 migration
 
 ## Decisions Taken

diff --git a/.agent/plans/2026-09-08-aauth-v10-spec-migration/implementation-plan.md b/.agent/plans/2026-09-08-aauth-v10-spec-migration/implementation-plan.md
@@ -1,7 +1,3 @@
----
-description: Phased implementation and verification of the AAuth v10 migration.
----
-
 # Implementation Plan - AAuth v10 repository migration
 
 Companion to [research.md](research.md), created 2026-09-08. This plan covers the

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1,6 @@
+# Markdown Authoring
+
+* Do not add YAML frontmatter to regular Markdown documents.
+* Begin each regular Markdown document with a single level-1 heading.
+* Preserve frontmatter only where tools require it as machine-readable metadata,
+  such as `*.instructions.md`, `*.prompt.md`, `*.agent.md`, and `SKILL.md` files.
diff --git a/README.md b/README.md
@@ -1,7 +1,4 @@
----
-title: AAuth SDK for .NET
-description: AAuth SDK for .NET, companion packages and runnable protocol demonstrations.
----
+# AAuth SDK for .NET
 
 [![CI](https://github.com/aauth-dev/dotnet-samples/actions/workflows/ci.yml/badge.svg)](https://github.com/aauth-dev/dotnet-samples/actions/workflows/ci.yml)
 [![NuGet](https://img.shields.io/nuget/vpre/AAuth)](https://www.nuget.org/packages/AAuth)

diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,4 @@
----
-title: AAuth .NET SDK Documentation
-description: Agent signing, server verification, companion packages and runnable workflows.
----
+# AAuth .NET SDK Documentation
 
 The AAuth .NET SDK (`AAuth` NuGet package) supports agent-side JWT signing,
 server-side verification, six Signature-Key schemes and four resource access

diff --git a/docs/advanced/clarification-chat.md b/docs/advanced/clarification-chat.md
@@ -1,7 +1,4 @@
----
-title: Clarification Chat
-description: Answer, narrow or cancel authenticated PS and AS clarification requests.
----
+# Clarification Chat
 
 > [Clarification Chat](https://explorer.aauth.dev/missions/clarification)
 

diff --git a/docs/advanced/error-handling.md b/docs/advanced/error-handling.md
@@ -1,7 +1,4 @@
----
-title: Error Handling
-description: Handle AAuth problem details, signature errors, and deferred consent failures.
----
+# Error Handling
 
 > [Error Codes](https://explorer.aauth.dev/foundations/errors)
 

diff --git a/docs/advanced/interaction-chaining.md b/docs/advanced/interaction-chaining.md
@@ -1,7 +1,4 @@
----
-title: Interaction Chaining
-description: Propagate deferred consent through intermediary resources.
----
+# Interaction Chaining
 
 When an intermediary resource calls a downstream resource and the downstream PS/AS requires user consent, the intermediary must propagate the interaction requirement back through the call chain to the original agent.
 

diff --git a/docs/advanced/key-management.md b/docs/advanced/key-management.md
@@ -1,7 +1,4 @@
----
-title: Key Management
-description: Software key persistence and explicit custom secure-key integration contracts.
----
+# Key Management
 
 > [Cryptographic Keys](https://explorer.aauth.dev/foundations/keys)
 

diff --git a/docs/advanced/missions.md b/docs/advanced/missions.md
@@ -1,7 +1,4 @@
----
-title: Missions
-description: Exact mission bytes, signed references and governed agent actions.
----
+# Missions
 
 > [Mission Lifecycle](https://explorer.aauth.dev/missions/lifecycle) | [Mission Comparison](https://explorer.aauth.dev/missions/compare)
 

diff --git a/docs/advanced/observability.md b/docs/advanced/observability.md
@@ -1,7 +1,4 @@
----
-title: Observability
-description: Subscribe to AAuth diagnostics without exposing token material.
----
+# Observability
 
 The AAuth SDK provides built-in OpenTelemetry-compatible tracing via `System.Diagnostics` — no external OTel package dependency required.
 

diff --git a/docs/advanced/platform-attestation.md b/docs/advanced/platform-attestation.md
@@ -1,7 +1,4 @@
----
-title: Platform Attestation
-description: Platform integration hooks and explicit limits of the software-key samples.
----
+# Platform Attestation
 
 > [Signing Modes](https://explorer.aauth.dev/foundations/schemes)
 

diff --git a/docs/concepts.md b/docs/concepts.md
@@ -1,7 +1,4 @@
----
-title: Protocol Concepts
-description: AAuth roles, access modes, governance, token purposes and supported companions.
----
+# Protocol Concepts
 
 AAuth is a protocol for autonomous agent authorization. This page maps protocol concepts to SDK types. For the full interactive protocol reference, see the [AAuth Explorer](https://explorer.aauth.dev/).
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,7 +1,4 @@
----
-title: Getting Started
-description: Enroll an agent and make signed AAuth requests with the .NET SDK.
----
+# Getting Started
 
 ## Prerequisites
 

diff --git a/docs/glossary.md b/docs/glossary.md
@@ -1,7 +1,4 @@
----
-title: Glossary and Acronyms
-description: Current AAuth roles, token purposes, cryptography and sample terminology.
----
+# Glossary and Acronyms
 
 A single reference for the acronyms, abbreviations, and short protocol terms
 used across this repository (samples, SDK, docs). AAuth-specific and

diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
@@ -1,7 +1,4 @@
----
-title: Configuration Reference
-description: Configure AAuth verification, token issuance, and deferred exchanges.
----
+# Configuration Reference
 
 All configurable options across the AAuth .NET SDK, grouped by component.
 

diff --git a/docs/reference/dependency-injection.md b/docs/reference/dependency-injection.md
@@ -1,7 +1,4 @@
----
-title: Dependency Injection
-description: Register agent provisioning, verification and policy services with explicit ownership.
----
+# Dependency Injection
 
 Register AAuth services in ASP.NET Core and hosted applications using the built-in DI extensions.
 

diff --git a/docs/server/authorization-policies.md b/docs/server/authorization-policies.md
@@ -1,7 +1,4 @@
----
-title: Authorization Policies
-description: Require verified AAuth scopes and roles in ASP.NET endpoints.
----
+# Authorization Policies
 
 The AAuth SDK integrates with ASP.NET Core's authorization system via `AAuthScopeRequirement`, `AAuthScopeHandler`, role claims, and a set of convenience policy registrations.
 

diff --git a/docs/server/challenge-middleware.md b/docs/server/challenge-middleware.md
@@ -1,7 +1,4 @@
----
-title: Challenge Middleware
-description: Issue resource-token challenges with explicit audience and mission context.
----
+# Challenge Middleware
 
 `AAuthChallengeMiddleware` automatically issues 401 challenges with resource tokens when an agent presents only an agent token but the resource requires an auth token.
 

diff --git a/docs/server/mission-governance.md b/docs/server/mission-governance.md
@@ -1,7 +1,4 @@
----
-title: Mission Governance (Server)
-description: Host authenticated mission approval, permission, audit and interaction endpoints.
----
+# Mission Governance (Server)
 
 > [Mission Lifecycle](https://explorer.aauth.dev/missions/lifecycle)
 

diff --git a/docs/server/multi-scheme-verification.md b/docs/server/multi-scheme-verification.md
@@ -1,7 +1,4 @@
----
-title: Multi-Scheme Verification
-description: Resolve and verify supported Signature Keys carriers under explicit role policy.
----
+# Multi-Scheme Verification
 
 > [Signature-Key Schemes](https://explorer.aauth.dev/foundations/schemes)
 

diff --git a/docs/server/replay-detection.md b/docs/server/replay-detection.md
@@ -1,7 +1,4 @@
----
-title: Replay Detection and Revocation
-description: Independent request replay protection and issuer-qualified token revocation.
----
+# Replay Detection and Revocation
 
 > [Signature Security](https://explorer.aauth.dev/foundations/signatures)
 

diff --git a/docs/server/resource-metadata.md b/docs/server/resource-metadata.md
@@ -1,7 +1,4 @@
----
-title: Resource Metadata
-description: Publish AAuth resource metadata and discover admitted issuer keys.
----
+# Resource Metadata
 
 > [Discovery](https://explorer.aauth.dev/foundations/discovery)
 

diff --git a/docs/server/token-issuance.md b/docs/server/token-issuance.md
@@ -1,7 +1,4 @@
----
-title: Token Issuance
-description: Issue bounded AAuth resource, agent, and authorization tokens.
----
+# Token Issuance
 
 > [Token Types](https://explorer.aauth.dev/foundations/tokens) | [Token Lifecycle](https://explorer.aauth.dev/tokens/lifecycle)
 

diff --git a/docs/server/verification-middleware.md b/docs/server/verification-middleware.md
@@ -1,7 +1,3 @@
----
-description: Typed JWT trust, selected-label HTTP signatures, and endpoint policy.
----
-
 # Verification Middleware
 
 `AAuthVerificationMiddleware` performs HTTP signature verification (RFC 9421 PoP) and JWT issuer signature verification in a single pass.

diff --git a/docs/signing-modes/agent-identity-jwks-uri.md b/docs/signing-modes/agent-identity-jwks-uri.md
@@ -1,7 +1,3 @@
----
-description: Metadata-based server key discovery and distinct direct JWKS signatures.
----
-
 # Server Identity (sig=jwks_uri)
 
 ## Overview

diff --git a/docs/signing-modes/key-rotation-jkt-jwt.md b/docs/signing-modes/key-rotation-jkt-jwt.md
@@ -1,7 +1,4 @@
----
-title: Key Rotation with jkt-jwt
-description: Generic naming-JWT delegation and AP refresh with distinct durable and ephemeral keys.
----
+# Key Rotation with jkt-jwt
 
 ## Overview
 

diff --git a/docs/signing-modes/overview.md b/docs/signing-modes/overview.md
@@ -1,7 +1,3 @@
----
-description: AAuth JWT carriers and generic HTTP Signature Keys schemes.
----
-
 # Signing Modes Overview
 
 AAuth agents use `jwt` for every resource, PS and AS request. The SDK also

diff --git a/docs/signing-modes/pseudonymous-hwk.md b/docs/signing-modes/pseudonymous-hwk.md
@@ -1,7 +1,3 @@
----
-description: Generic inline public-key signatures using the hwk scheme.
----
-
 # Pseudonymous Signatures (sig=hwk)
 
 ## Overview

diff --git a/docs/workflows/bootstrap-enrollment.md b/docs/workflows/bootstrap-enrollment.md
@@ -1,7 +1,4 @@
----
-title: Bootstrap and Agent Enrollment
-description: Provision durable agent keys with signed enrollment and provider-assigned identities.
----
+# Bootstrap and Agent Enrollment
 
 ## Overview
 

diff --git a/docs/workflows/call-chaining.md b/docs/workflows/call-chaining.md
@@ -1,7 +1,4 @@
----
-title: Call Chaining
-description: Preserve authorization context across multi-hop agent calls.
----
+# Call Chaining
 
 Call chaining enables multi-hop delegation where a resource acts as an agent to downstream resources, preserving the full authorization chain via nested `act` claims.