Phase 5: Documentation (DOC-01) + Phase 4 closeout

.planning/REQUIREMENTS.md

@@ -65,10 +65,11 @@ Remaining open work (from `FIX-PLAN.md`), batched toward the first `v2.0.0-beta`
 - [x] **VAL-02**: `[SettingsProperty(AllowEmpty=false)]` rejects `""`/whitespace/unsubstituted `${ENV:-}` at bind, not just `null`; `TypeConverter.ValidateNullAcceptance` (naturally rides on VAL-01) (client pre-beta)
 - [ ] **API-02**: `AddSimpleSettings(...)` exposes the `ISettingsCollection` (return value or resolvable service — shape TBD in planning) (client pre-beta #4)
 
-### AOT/Trim & Documentation
+### Documentation
 
-- [ ] **AOT-01**: Annotate reflection entry points (`[RequiresDynamicCode]`/`[RequiresUnreferencedCode]`) and/or document the AOT/trim limitation before stable (A1)
-- [ ] **DOC-01**: Refresh README to canonical naming and current repo/package links
+- [x] **DOC-01**: Refresh README + docs/ to canonical `ExistForAll.SimpleSettings` naming and current repo/package links; document the Phase 1–4 security/behavior guidance (secret-redaction; validator secret-safety incl. constructors; opt-in/deferred DI validation; validate⇒discoverable coupling; spaced-secrets binding; Phase-3 breaking-change list)
+
+*(AOT-01 was mapped here but was **deferred to a future v2.1 milestone** on 2026-07-19 — see v2 Requirements → Deferred.)*
 
 ### Release
 
@@ -85,6 +86,7 @@ Deferred / held. Tracked but not in the current roadmap.
 ### Deferred
 
 - **PERF-03**: Tiered/lazy compiled property setter — only if set-*time* shows up in a real profile (P3b); a compiled setter was tried and reverted (regressed cold scan, no warm gain)
+- **AOT-01** (A1): Annotate reflection entry points (`[RequiresDynamicCode]`/`[RequiresUnreferencedCode]`) and/or document the AOT/trim limitation — **DEFERRED to a future v2.1 milestone** (2026-07-19, Phase-5 discussion). The annotations are additive/non-breaking, so they need not batch pre-beta; adding them post-stable is safe. Reflection entry points: `SettingsBuilder.CreateBuilder`/`.ScanAssemblies`/`.GetSettings`, `AddSimpleSettings(...)` (all funnel into `Reflection.Emit` with `RunAndCollect`).
 
 ## Out of Scope
 
@@ -115,19 +117,20 @@ Deferred / held. Tracked but not in the current roadmap.
 | COLL-03 | Phase 4 | Complete |
 | VAL-01 | Phase 4 | Complete |
 | VAL-02 | Phase 4 | Complete |
-| API-02 | Phase 4 | Pending |
-| AOT-01 | Phase 5 | Pending |
-| DOC-01 | Phase 5 | Pending |
+| API-02 | Phase 4 | ✓ Complete (#35) |
+| AOT-01 | v2.1 (deferred) | Deferred |
+| DOC-01 | Phase 5 | Complete |
 | REL-01 | Phase 6 | Pending |
 
 **Coverage:**
 
-- v1 requirements: 20 total (added Phase 4 engine reqs COLL-02/COLL-03/VAL-02/API-02 + promoted VAL-01 from Held)
-- Mapped to phases: 20
+- v1 in-milestone requirements: 19 (was 20; **AOT-01 deferred to v2.1** on 2026-07-19)
+- Mapped to phases: 19
 - Unmapped: 0 ✓
-- Complete: 12 (Phase 1 SEC-01/SEC-02/EXC-01 #27/#28; Phase 2 COLL-01/TEST-01/TEST-02/TEST-03 + ENG-01/T7 #29; Phase 3 API-01/PKG-01/PKG-02/SRC-02 #31); Pending: 8 (Phase 4 COLL-02/COLL-03/VAL-01/VAL-02/API-02; Phase 5 AOT-01/DOC-01; Phase 6 REL-01)
+- Complete: 17 (Phase 1 SEC-01/SEC-02/EXC-01 #27/#28; Phase 2 COLL-01/TEST-01/TEST-02/TEST-03 + ENG-01/T7 #29; Phase 3 API-01/PKG-01/PKG-02/SRC-02 #31; Phase 4 COLL-02/COLL-03/VAL-01/VAL-02/API-02 #33/#34/#35); Pending: 2 (Phase 5 DOC-01; Phase 6 REL-01)
 - Validated (shipped, no phase): 13
 
 ---
 *Requirements defined: 2026-07-13*
-*Last updated: 2026-07-14 — Phase 4 "Collection & Validation Binding" formalized (COLL-02/COLL-03/VAL-02/API-02 added; VAL-01 promoted from Held D1); AOT/Docs → Phase 5, beta → Phase 6. ENG-01/T7 complete (#29). GSD is the source of truth; FIX-PLAN.md frozen as historical reference.*
+*Last updated: 2026-07-19 — Phase 5 scoped to Documentation (DOC-01) only; **AOT-01 deferred to a future v2.1 milestone** (additive/non-breaking annotations need not batch pre-beta). Phase 4 marked complete in traceability (COLL-02/COLL-03/VAL-01/VAL-02/API-02, #33/#34/#35).*
+*Prior: 2026-07-14 — Phase 4 "Collection & Validation Binding" formalized (COLL-02/COLL-03/VAL-02/API-02 added; VAL-01 promoted from Held D1); AOT/Docs → Phase 5, beta → Phase 6. ENG-01/T7 complete (#29). GSD is the source of truth; FIX-PLAN.md frozen as historical reference.*

.planning/ROADMAP.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-**Status (2026-07-14):** Phases 1–3 complete (Phase 1 #27/#28, Phase 2 #30, Phase 3 #31; ENG-01/T7 #29). `master` @ `7f9e17c`. Active phase is **Phase 4 — Collection & Validation Binding** (new engine phase for the client pre-beta requirements); AOT/Trim & Docs renumbered to Phase 5, first beta to Phase 6.
+**Status (2026-07-19):** Phases 1–4 complete (Phase 1 #27/#28, Phase 2 #30, Phase 3 #31, Phase 4 #33/#34/#35; ENG-01/T7 #29). `master` @ `0c858fa`. Active phase is **Phase 5 — Documentation** (docs-only; AOT-01 deferred to a future v2.1 milestone); first beta is Phase 6.
 
 The binding engine already ships and works. This milestone is a hardening + pre-stable
 cleanup pass that batches every remaining breaking change and safety fix before cutting the
@@ -11,8 +11,10 @@ consumers one catchable, structured exception base (Phase 1), proves binding cor
 across collection/nullable/converter shapes and closes the generator concurrency race with
 tests (Phase 2), trims and corrects the public surface, packaging, and command-line binder
 (Phase 3), binds collections and settings validation correctly across empty/sequence/validator
-shapes (Phase 4), tells consumers the truth about AOT/trim and refreshes the docs (Phase 5), and
-finally publishes the batched result as the first beta (Phase 6). Everything serves the core
+shapes (Phase 4), refreshes the docs to canonical naming and accurate, current content (Phase 5), and
+finally publishes the batched result as the first beta (Phase 6). AOT/trim honesty (AOT-01) is
+deferred to a future v2.1 milestone — its `[RequiresDynamicCode]`/`[RequiresUnreferencedCode]`
+annotations are additive and non-breaking, so they need not batch pre-beta. Everything serves the core
 value: config → typed settings maps accurately, and never leaks a secret doing it.
 
 ## Phases
@@ -25,8 +27,8 @@ value: config → typed settings maps accurately, and never leaks a secret doing
 - [x] **Phase 1: Exception Safety & Public Hierarchy** — ✓ COMPLETE (S1 #27, C2 #28 merged 2026-07-14) - No secret leaks; one catchable, structured `SimpleSettingsException` base
 - [x] **Phase 2: Binding Correctness & Engine Test Hardening** - Collections/nullable/converters verified; generator race closed by tests *(ENG-01/T7 done #29; COLL-01 + TEST-01/02/03 remain)* (completed 2026-07-14)
 - [x] **Phase 3: Public Surface, Packaging & Binder Cleanup** - Meaningful public surface; per-TFM deps; correct command-line parsing (completed 2026-07-14)
-- [ ] **Phase 4: Collection & Validation Binding** - Empty/sequence collection binding, working settings validation, and DI collection surface (client pre-beta engine requirements)
-- [ ] **Phase 5: AOT/Trim Honesty & Documentation** - Honest AOT/trim signals; canonically-named docs
+- [x] **Phase 4: Collection & Validation Binding** — ✓ COMPLETE (Waves 1–3 merged #33/#34/#35, 2026-07-19) - Empty/sequence collection binding, working settings validation, and DI collection surface (client pre-beta engine requirements)
+- [x] **Phase 5: Documentation** - Canonically-named, accurate, current docs (README + docs/); AOT-01 deferred to a future v2.1 milestone (completed 2026-07-20)
 - [ ] **Phase 6: First v2.0.0-beta Release** - Batched breaking changes ship as an installable pre-release
 
 ## Phase Details
@@ -92,6 +94,7 @@ value: config → typed settings maps accurately, and never leaks a secret doing
 **Goal**: Collections bind correctly across empty, comma-scalar, and YAML-sequence shapes; declared settings validation actually runs; and the DI extension exposes the settings collection — the client-requested engine features batched before beta.
 **Depends on**: Phase 3
 **Requirements**: COLL-02, COLL-03, VAL-01, VAL-02, API-02
+**Status**: ✓ COMPLETE — Waves 1–3 merged (#33 Waves 1–2, #34 planning, #35 Wave 3) to `master` @ `0c858fa` on 2026-07-19. All 6 success criteria MET (VERIFICATION.md — 6/6, non-vacuous tests); security gate cleared (SECURITY.md — 15/15 threats closed, D-06 secret-redaction gate signed off); suite 153/153 on net8 + net10.
 **Success Criteria** (what must be TRUE):
 
   1. An unset `T[]` / `List<T>` / `IEnumerable<T>` binds to an empty collection, never `null` (COLL-02).
@@ -101,7 +104,7 @@ value: config → typed settings maps accurately, and never leaks a secret doing
   5. `AddSimpleSettings(...)` exposes the `ISettingsCollection` (return value or resolvable service) (API-02).
   6. After COLL-03 edits `ConfigurationBinder.BindPropertySettings`, the S1/SEC-01 secret-redaction invariant is re-verified; suite green on net8 + net10.
 
-**Plans**: 4/5 plans executed
+**Plans**: 5/5 plans complete
 
 **Wave 1**
 
@@ -115,20 +118,33 @@ value: config → typed settings maps accurately, and never leaks a secret doing
 
 **Wave 3** *(blocked on Wave 2 completion)*
 
-- [ ] 04-04-PLAN.md — API-02 ISettingsCollection exposure (DI singleton + out-overload, D-15) + VAL-01 deferred DI-resolved validator runner (D-11/Q3) [Wave 3, depends on 04-03]
+- [x] 04-04-PLAN.md — API-02 ISettingsCollection exposure (DI singleton + out-overload, D-15) + VAL-01 deferred DI-resolved validator runner (D-11/Q3, DIM-bridge dispatch) [Wave 3, depends on 04-03]
 
-### Phase 5: AOT/Trim Honesty & Documentation
+### Phase 5: Documentation
 
-**Goal**: Consumers get honest signals about AOT/trim support and accurate, canonically-named documentation.
+**Goal**: Consumers get accurate, canonically-named documentation — the consumer-facing README and the docs/ folder tell the truth about the current API and carry the Phase 1–4 security/behavior guidance.
 **Depends on**: Phase 4
-**Requirements**: AOT-01, DOC-01
+**Requirements**: DOC-01
 **Success Criteria** (what must be TRUE):
 
-  1. Public reflection-based entry points carry `[RequiresDynamicCode]`/`[RequiresUnreferencedCode]` annotations and/or the AOT/trim limitation is documented before stable.
-  2. Building an AOT/trimmed consumer surfaces a warning (or finds a clearly documented limitation) rather than failing silently.
-  3. README uses the canonical `ExistForAll.SimpleSettings` name and links to current repo/package paths (no legacy `existall`/`SimpleConfig` references).
+  1. README uses the canonical `ExistForAll.SimpleSettings` name and links to current repo/package paths (no legacy `SimpleConfig` repo/product references; repo stays `existall/SimpleSettings`).
+  2. The README code example reflects the real API (`[SettingsSection]` / `[SettingsProperty(DefaultValue=…)]`), not the stale `[DefaultValue]` form, and the install command + logo resolve.
+  3. The mandated Phase 1–4 guidance is documented (secret-redaction; validators must not echo secrets, incl. constructors; opt-in/deferred DI `ValidateSimpleSettings()`; validate⇒discoverable coupling; spaced-secrets bind via `AddCommandLine`; Phase-3 breaking-change list) — concise in README, detailed in docs/.
+  4. The docs/ folder carries no legacy `SimpleConfig` naming or dead `existall/SimpleConfig` links, and package metadata (`<Description>`, repo/package URLs, logo) is canonical.
 
-**Plans**: TBD
+**Note**: AOT-01 (annotate reflection entry points / document the AOT-trim limitation) was **deferred to a future v2.1 milestone** during Phase-5 discussion (2026-07-19). Rationale: `[RequiresDynamicCode]`/`[RequiresUnreferencedCode]` are additive, non-breaking attributes, so they need not batch into the pre-beta window; adding them post-stable is safe. See REQUIREMENTS.md (AOT-01 → Deferred).
+
+**Plans**: 4/4 plans complete
+
+**Wave 1** *(parallel — no file overlap)*
+
+- [x] 05-01-PLAN.md — docs/ canonicalization: rename the extension guide to a canonical filename + repoint its 5 in-docs inbound links; drop the residual legacy parenthetical in getting_started.md (D-05) [Wave 1]
+- [x] 05-02-PLAN.md — package metadata: fix `<Description>` typo + legacy `<PackageTags>` token in src/Directory.Build.props; build sanity (D-06) [Wave 1]
+- [x] 05-03-PLAN.md — new deep-guidance page docs/Security.md: the 6 mandated Phase 1–4 items (secret-redaction + 2 caveats, validator secret-safety incl. constructor, opt-in/deferred `ValidateSimpleSettings()` on `IServiceProvider`, validate⇒discoverable, `AddCommandLine` spaced values, v1→v2 breaking-change list) (D-04 deep) [Wave 1]
+
+**Wave 2** *(blocked on Wave 1 completion)*
+
+- [x] 05-04-PLAN.md — README full rewrite: canonical logo/title, `dotnet add package` ×3, canonical ToC (incl. renamed page + Security), correct `[SettingsProperty(DefaultValue=…)]` quickstart, trimmed positioning, concise Security + migration sections; phase-final 13-gate grep sweep + `dotnet build`/`pack` (D-01/D-02/D-03/D-04) [Wave 2, depends on 05-01/05-02/05-03]
 
 ### Phase 6: First v2.0.0-beta Release
 
@@ -154,6 +170,6 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
 | 1. Exception Safety & Public Hierarchy | n/a (shipped) | ✓ Complete | 2026-07-14 (#27/#28) |
 | 2. Binding Correctness & Engine Test Hardening | 2/2 | Complete    | 2026-07-14 |
 | 3. Public Surface, Packaging & Binder Cleanup | 2/2 | Complete    | 2026-07-14 |
-| 4. Collection & Validation Binding | 4/5 | In Progress|  |
-| 5. AOT/Trim Honesty & Documentation | 0/TBD | Not started | - |
+| 4. Collection & Validation Binding | 5/5 | ✓ Complete | 2026-07-19 (#35) |
+| 5. Documentation | 4/4 | Complete    | 2026-07-20 |
 | 6. First v2.0.0-beta Release | 0/TBD | Not started | - |

.planning/STATE.md

@@ -2,19 +2,19 @@
 gsd_state_version: 1.0
 milestone: v2.0.0
 milestone_name: milestone
-current_phase: 04
-current_phase_name: collection-validation-binding
-status: executing
-stopped_at: Completed 04-04-PLAN.md (VAL-01 DI path + API-02, Wave 3) — all 5 Phase 4 plans landed; phase verify + secure + mark-complete pending
-last_updated: "2026-07-15T18:00:00.000Z"
-last_activity: 2026-07-15
-last_activity_desc: Phase 04 Plan 04 (Wave 3) executed + reviewed
+current_phase: 6
+current_phase_name: First v2.0.0-beta Release
+status: completed
+stopped_at: Completed 05-04. Phase 05 plan set complete.
+last_updated: "2026-07-20T09:35:05.147Z"
+last_activity: 2026-07-20
+last_activity_desc: Phase 05 complete, transitioned to Phase 6
 progress:
   total_phases: 6
-  completed_phases: 2
-  total_plans: 9
-  completed_plans: 9
-  percent: 33
+  completed_phases: 4
+  total_plans: 13
+  completed_plans: 13
+  percent: 67
 ---
 
 # Project State
@@ -24,22 +24,22 @@ progress:
 See: .planning/PROJECT.md (updated 2026-07-13)
 
 **Core value:** Correctness of binding — config → strongly-typed settings maps accurately across every supported shape (sections, arrays/enumerables, defaults, nullable, custom converters).
-**Current focus:** Phase 04 — collection-validation-binding
+**Current focus:** Phase 05 — Documentation
 
 ## Current Position
 
-Phase: 04 (collection-validation-binding) — EXECUTING (all 5 plans landed; verify + secure + mark-complete pending)
-Plan: 5 of 5 — complete
-Status: Wave 3 (04-04) executed + reviewed; ready for phase verify
-Last activity: 2026-07-15 — Phase 04 Plan 04 (Wave 3) executed + reviewed
+Phase: 6 — First v2.0.0-beta Release
+Next: Phase 05 verify/ship gate; then Phase 06 beta release
+Status: Phase 05 all four plans complete — README + docs/ + props canonical, packages repack cleanly
+Last activity: 2026-07-20 — Phase 05 complete, transitioned to Phase 6
 
-Progress: [███░░░░░░░] 33%
+Progress: [██████████] 100% (13/13 plans)
 
 ## Performance Metrics
 
 **Velocity:**
 
-- Total plans completed: 4
+- Total plans completed: 8
 - Average duration: —
 - Total execution time: 0 hours
 
@@ -49,6 +49,7 @@ Progress: [███░░░░░░░] 33%
 |-------|-------|-------|----------|
 | 02 | 2 | - | - |
 | 03 | 2 | - | - |
+| 05 | 4 | - | - |
 
 **Recent Trend:**
 
@@ -65,6 +66,10 @@ Progress: [███░░░░░░░] 33%
 | Phase 04 P03 | 5min | 2 tasks | 10 files |
 | Phase 04 P05 | 3min | 1 tasks | 2 files |
 | Phase 04 P04 | ~35min | 2 tasks | 5 files |
+| Phase 05 P01 | 5min | 2 tasks | 5 files |
+| Phase 05 P02 | 3min | 1 tasks | 1 files |
+| Phase 05 P03 | 4min | 2 tasks | 1 files |
+| Phase 05 P04 | 2min | 2 tasks | 1 files |
 
 ## Accumulated Context
 
@@ -91,6 +96,9 @@ Recent decisions affecting current work:
 - [Phase 04]: 04-05 VAL-02: reuse value-free SettingsPropertyNullException for empty/whitespace rejection — already excluded from the ValuesPopulator:122 redaction filter, so no filter change
 - [Phase 04]: 04-05 VAL-02: reject guard placed ahead of 04-01's Func<object> list null-result factory dispatch and gated on _throwOnNull; accept path and factory dispatch untouched
 - [Phase 04]: 04-04 VAL-01 DI path + API-02: ISettingsCollection exposed via a DI singleton + an AddSimpleSettings(out ISettingsCollection, Action?) overload; deferred opt-in IServiceProvider.ValidateSimpleSettings() runs DI-registered ISettingValidation<T> from a fresh scope (IServiceScopeFactory), dispatches via the DIM bridge (no reflection), and throws the same value-free SettingsValidationException as the core path via the shared ThrowIfAny. Runner is internal; DI path is additive (reads no attribute).
+- [Phase ?]: 05-02: Replaced legacy SimpleConfig PackageTags token with canonical SimpleSettings; fixed Description typo appliaction->application
+- [Phase ?]: 05-03: Placed deep Phase 1-4 security/behavior guidance in a dedicated new docs/Security.md (stable README deep-link target); stated the redaction invariant with both carve-outs without over-claiming
+- [Phase ?]: 05-04: README rewritten against source-verified API (canonical logo, dotnet-add x3, correct [SettingsProperty(DefaultValue)] quickstart); concise Security notes + v1->v2 migration deep-link docs/Security.md; 13 DOC-VERIFICATION gates + dotnet build/pack green
 
 ### Pending Todos
 
@@ -103,6 +111,7 @@ None yet.
 ### Roadmap Evolution
 
 - Phase 4 inserted: Phase 4 Collection & Validation Binding formalized (COLL-02/COLL-03/VAL-01/VAL-02/API-02); AOT/Docs renumbered to Phase 5, beta to Phase 6
+- Phase 5 rescoped (2026-07-19): "AOT/Trim Honesty & Documentation" → "Documentation" (DOC-01 only); AOT-01 deferred to a future v2.1 milestone — additive/non-breaking annotations need not batch pre-beta
 
 ## Deferred Items
 
@@ -113,9 +122,10 @@ Items acknowledged and carried forward:
 | Held feature | VAL-01 Validations API (D1) | Promoted → Phase 4 (2026-07-14) | 2026-07-13 |
 | Held feature | EQ-01 EqualityCompererCreator (D2) | Held | 2026-07-13 |
 | Perf | PERF-03 compiled setter (P3b) | Deferred (profile-gated) | 2026-07-13 |
+| AOT/Trim | AOT-01 annotations/docs (A1) | Deferred → v2.1 milestone | 2026-07-19 |
 
 ## Session Continuity
 
-Last session: 2026-07-15T13:58:04.982Z
-Stopped at: Completed 04-05-PLAN.md (VAL-02) — Phase 4 all 5 plans done
+Last session: 2026-07-20T09:26:57.599Z
+Stopped at: Completed 05-04. Phase 05 plan set complete.
 Resume file: None