[vbreuss]

Align the Awaiten docs with the shared docs style guide so they read and build like the other libraries on docs.testably.org.

• AGENTS.md gets a Documentation section with the guide's short rules; the agent docs no longer prescribe :::danger for error diagnostics or slug links to the diagnostics page.
• Every page has a description; the H1 is the title (also on the benchmarks page); redundant title, sidebar_position and category position entries are gone.
• The category folders get unique NN- prefixes (03-core-concepts to 07-hosting, same visible order) and all links point at the files with relative paths, so they also work on GitHub; the docs-test scaffolds and the web sample README follow the rename.
• Categories no longer set collapsed, so they are collapsed by default like in the other libraries.
• The start page follows the template (pitch, example, "Why Awaiten?", "Where to go next" including the benchmarks); its getting-started steps and package table moved to the getting-started page, which now has requirements (SDK 10.0.300, C# 11, target frameworks), a complete first example and the real AWT101 message.
• Callouts follow the guide's meanings: italic notes become admonitions, the former :::caution boxes become :::tip where they give advice ("When not to reach for this", "Last resort") and :::warning where they describe a pitfall, diagnostic severities keep their red :::danger[Error] and :::warning[Warning] boxes, and one long rationale moves into <details>.
• Examples use explicit types instead of var, the architecture test uses await That(...), the aweXpect.Reflection link is site-absolute, and the text uses US spelling without em dashes.
• The README gets an ## Installation section with a plain dotnet add package command.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

Test Results

   27 files  ±0     27 suites  ±0   1h 23m 11s ⏱️ + 14m 5s
1 704 tests ±0  1 704 ✅ ±0  0 💤 ±0  0 ❌ ±0 
8 255 runs  ±0  8 255 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit 14c22e8. ± Comparison against base commit 49f3095.

This pull request removes 24 and adds 24 tests. Note that renamed tests count towards both.

Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(core-concepts/01-lifetimes·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(core-concepts/02-scopes·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(core-concepts/03-async-initialization·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(core-concepts/04-disposal·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(hosting/01-msdi-bridge·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(hosting/02-external-services·mdx)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(lifetime/01-owned·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(lifetime/02-lifetime-safety·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(lifetime/03-lifecycle-hooks·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(registration/01-factories-and-instances·md)
…

Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(03-core-concepts/01-lifetimes·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(03-core-concepts/02-scopes·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(03-core-concepts/03-async-initialization·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(03-core-concepts/04-disposal·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(04-registration/01-factories-and-instances·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(04-registration/02-decorators·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(04-registration/03-composites·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(04-registration/04-keyed-services·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(04-registration/05-open-generics·md)
Awaiten.Docs.Tests.DocsPagesTests ‑ CodeBlocks_ShouldCompile(04-registration/06-scanning·md)
…

[github-actions]

🚀 Benchmark Results

Details

BenchmarkDotNet v0.15.8, Linux Ubuntu 26.04.1 LTS (Resolute Raccoon)

AMD EPYC 9V74 3.69GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.303

[Host] : .NET 10.0.14 (10.0.14, 10.0.1426.52326), X64 RyuJIT x86-64-v4
Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10

Realistic	Mean	Error	StdDev	Ratio	Allocated	Alloc Ratio
baseline*	253.7 ns	3.10 ns	2.90 ns	1.24	568 B	1.00
Awaiten	203.8 ns	1.00 ns	0.94 ns	1.00	568 B	1.00
MsDI	460.1 ns	4.37 ns	3.88 ns	2.26	1104 B	1.94
Autofac	5,138.4 ns	44.74 ns	41.85 ns	25.22	10784 B	18.99
Jab	156.2 ns	1.06 ns	0.99 ns	0.77	432 B	0.76
DryIoc	344.5 ns	4.50 ns	4.20 ns	1.69	944 B	1.66
SimpleInjector	555.0 ns	6.73 ns	5.97 ns	2.72	1096 B	1.93
PureDI	148.4 ns	1.18 ns	1.11 ns	0.73	632 B	1.11

Details

BenchmarkDotNet v0.15.8, Linux Ubuntu 26.04.1 LTS (Resolute Raccoon)

AMD EPYC 9V74 3.69GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.303

[Host] : .NET 10.0.14 (10.0.14, 10.0.1426.52326), X64 RyuJIT x86-64-v4
Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10

Resolve	Size	Mean	Error	StdDev	Ratio	Allocated	Alloc Ratio
baseline*	8	6.063 ns	0.1267 ns	0.1058 ns	1.02	-	NA
Awaiten	8	5.919 ns	0.1340 ns	0.1253 ns	1.00	-	NA
MsDI	8	6.487 ns	0.0078 ns	0.0069 ns	1.10	-	NA
Autofac	8	84.856 ns	0.5258 ns	0.4919 ns	14.34	656 B	NA
Jab	8	2.440 ns	0.0908 ns	0.0758 ns	0.41	-	NA
PureDI	8	4.518 ns	0.0194 ns	0.0162 ns	0.76	-	NA
DryIoc	8	6.761 ns	0.1312 ns	0.1227 ns	1.14	-	NA
SimpleInjector	8	8.479 ns	0.0100 ns	0.0094 ns	1.43	-	NA
baseline*	256	6.949 ns	0.1497 ns	0.1401 ns	1.11	-	NA
Awaiten	256	6.286 ns	0.0040 ns	0.0033 ns	1.00	-	NA
MsDI	256	6.426 ns	0.0082 ns	0.0076 ns	1.02	-	NA
Autofac	256	85.213 ns	0.8800 ns	0.8232 ns	13.56	656 B	NA
Jab	256	36.174 ns	0.0137 ns	0.0121 ns	5.75	-	NA
PureDI	256	6.222 ns	0.0077 ns	0.0064 ns	0.99	-	NA
DryIoc	256	6.510 ns	0.1344 ns	0.1050 ns	1.04	-	NA
SimpleInjector	256	8.486 ns	0.0219 ns	0.0183 ns	1.35	-	NA

Details

BenchmarkDotNet v0.15.8, Linux Ubuntu 26.04.1 LTS (Resolute Raccoon)

AMD EPYC 9V74 3.64GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.303

[Host] : .NET 10.0.14 (10.0.14, 10.0.1426.52326), X64 RyuJIT x86-64-v4
Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10

Build	Size	Mean	Error	StdDev	Ratio	Allocated	Alloc Ratio
baseline*	8	10.469 ns	0.1196 ns	0.1119 ns	0.69	208 B	1.00
Awaiten	8	15.130 ns	0.1164 ns	0.1031 ns	1.00	208 B	1.00
MsDI	8	1,280.092 ns	25.0674 ns	22.2216 ns	84.61	5688 B	27.35
Autofac	8	26,688.603 ns	174.4770 ns	163.2059 ns	1,764.08	32478 B	156.14
Jab	8	6.574 ns	0.1640 ns	0.1454 ns	0.43	96 B	0.46
PureDI	8	11.680 ns	0.2901 ns	0.2713 ns	0.77	128 B	0.62
DryIoc	8	652.585 ns	5.7812 ns	5.4078 ns	43.13	1528 B	7.35
SimpleInjector	8	9,308.361 ns	68.2189 ns	60.4743 ns	615.27	24761 B	119.04
baseline*	256	77.459 ns	1.1840 ns	1.1075 ns	0.75	4176 B	1.00
Awaiten	256	103.083 ns	0.2447 ns	0.2043 ns	1.00	4176 B	1.00
MsDI	256	10,499.295 ns	272.8128 ns	255.1893 ns	101.85	61016 B	14.61
Autofac	256	634,017.368 ns	8,335.8195 ns	7,797.3308 ns	6,150.58	740316 B	177.28
Jab	256	48.964 ns	0.5782 ns	0.5408 ns	0.47	2080 B	0.50
PureDI	256	55.081 ns	0.0687 ns	0.0536 ns	0.53	2112 B	0.51
DryIoc	256	34,599.898 ns	277.0033 ns	259.1091 ns	335.65	80013 B	19.16
SimpleInjector	256	264,384.824 ns	2,475.9589 ns	2,067.5378 ns	2,564.79	573043 B	137.22

baseline* rows show the corresponding Awaiten benchmark from the most recent successful main branch build with results, for regression comparison.