Build the MagicSettings configuration runtime

[magiccodingman]

Summary

Builds the initial MagicSettings platform as a reusable .NET 10 library suite:

• MagicSettings — code-defined templates, one persistent appsettings.json, safe reconciliation, explicit versioned migrations, validation, atomic snapshots, file watching, provider precedence, IConfiguration / options integration, diagnostics, dynamic remote synchronization, and asynchronous secrets.
• MagicSettings.Share — shared schema manifests, signed synchronization contracts, node-specific remote snapshots, migration reports, review items, request proofs, and secret contracts.
• MagicSettings.Server — storage-agnostic enrollment and synchronization helpers, proof verification, replay protection, per-node records, credential approval/revocation/rotation, conservative migration-report handling, and secret-resolution hooks.
• MagicSettings.Tests — xUnit coverage across generation, reconciliation, arrays, migrations, precedence, endpoint bootstrap, identity lifecycle, enrollment, proof binding, replay protection, rotation, revocation, secrets, and server retention behavior.
• Documentation — expanded README plus a structured /wiki, a package-by-package public API reference, and an AI-agent task guide with concrete integration workflows, security boundaries, extension points, and anti-patterns.

Core behavior

The effective precedence model is:

persistent appsettings.json
    → custom providers
    → MagicSettings__ OS/process environment variables
    → remote in-memory control-plane snapshot

The code-defined template maintains the persistent file, but transient provider, environment, and remote values are never serialized back to disk.

Each application instance remains authoritative over its own schema, local file, migration history, identity, and effective settings. Remote communication is always client-initiated. The server never needs to contact a node, and one node's migration never mutates another node.

Control-plane endpoint bootstrap is intentionally local-only:

explicit ConfigureAsync(...)
    → dedicated OS environment variable
    → persistent local appsettings value
    → code fallback

Remote overrides cannot redirect the node's own trust authority.

The stable node identity can authenticate other APIs through fresh proof-of-possession signatures bound to audience, HTTP method, target URI, body hash, lifetime, and one-time nonce. The private key is not exposed as an application API. Planned rotation uses a continuity proof; destructive reset creates a new unapproved node identity.

Client-side remote migration may change what the current node consumes, but potentially destructive server-side effects are submitted as review items. Server helpers retain original values rather than silently deleting sensitive or legacy data.

Remote values are sticky by default during outages; expiration is explicit per value.

Documentation coverage

• wiki/api-reference.md catalogs the developer-facing APIs across all three packages, including options, methods, contracts, persistence semantics, expected usage, and security warnings.
• wiki/agent-usage.md maps common development tasks to the exact APIs and call order, with 24 integration workflows and explicit agent anti-patterns.
• The root README and wiki index link both documents prominently.

Validation

The repository contains the normal readable source tree; the former encoded bootstrap payload has been removed.

GitHub Actions on commit 76e35014af9f17c7616cbb6e16dd6add4c30ba75 passed:

• dotnet restore MagicSettings.sln
• dotnet build MagicSettings.sln --configuration Release --no-restore
• dotnet test MagicSettings.sln --configuration Release --no-build

Result: Release build passed and all 22 xUnit tests passed.