docs: regenerate documentation for v4.1.0 release

Update README structure and all formal documentation with
production links, Code Standards section, and improved formatting.

Author: abitofhelp

README.md

@@ -1,26 +1,54 @@
 # Functional Programming Library for Ada 2022
 
-[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE) [![Ada](https://img.shields.io/badge/Ada-2022-blue.svg)](https://ada-lang.io) [![SPARK](https://img.shields.io/badge/SPARK-Proved-brightgreen.svg)](https://www.adacore.com/about-spark) [![Alire](https://img.shields.io/badge/Alire-2.0+-blue.svg)](https://alire.ada.dev)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE) [![Ada](https://img.shields.io/badge/Ada-2022-blue.svg)](https://ada-lang.io) [![SPARK](https://img.shields.io/badge/SPARK-Proved-green.svg)](https://www.adacore.com/about-spark) [![Alire](https://img.shields.io/badge/Alire-2.0+-blue.svg)](https://alire.ada.dev)
 
-**Version:** 4.0.0  
-**Date:** December 12, 2025  
+**Version:** 4.1.0<br>
+**Date:** 2025-12-18<br>
 **SPDX-License-Identifier:** BSD-3-Clause<br>
 **License File:** See the LICENSE file in the project root<br>
-**Copyright:** © 2025 Michael Gardner, A Bit of Help, Inc.<br>  
-**Status:** Released  
+**Copyright:** © 2025 Michael Gardner, A Bit of Help, Inc.<br>
+**Status:** Released
 
 ## Overview
 
 A production-ready Ada 2022 library providing functional programming abstractions for type-safe computation. Implements `Result<T,E>`, `Option<T>`, `Either<L,R>` monadic types, and `Scoped` RAII guards with 80+ composable operations enabling railway-oriented programming, explicit error handling, optional value management, and automatic resource cleanup.
 
 Designed for safety-critical, embedded, and high-assurance applications with full SPARK compatibility.
 
+## Features
+
+### Core Types (80+ operations)
+
+| Type | Operations | Purpose |
+|------|------------|---------|
+| **Result[T,E]** | 30 | Success/failure with typed errors |
+| **Option[T]** | 25 | Optional values (presence/absence) |
+| **Either[L,R]** | 20 | Disjoint unions (one of two types) |
+| **Try** | 6 + child packages | Exception-to-functional bridges |
+| **Scoped** | 2 | RAII resource guards |
+
+### Embedded Systems Ready
+
+- **Preelaborate/Pure** categorization on all packages
+- **Zero heap allocation** - Stack-based discriminated records only
+- **No controlled types in core** - No finalization overhead
+- **No tasking dependencies** - Ravenscar profile compatible
+- **Bounded memory** - Fixed-size structures
+- **No OS dependencies** - Pure Ada 2022
+
+### Production Quality
+
+- **Comprehensive test coverage** (90%+ code coverage)
+- **Zero dependencies** - Ada 2022 standard library only
+- **Comprehensive contracts** - Pre/Post conditions throughout
+- **Cross-platform** - POSIX and Windows tested
+
 ## SPARK Formal Verification
 
 <table>
 <tr>
 <td width="120"><strong>Status</strong></td>
-<td><img src="https://img.shields.io/badge/SPARK-Proved-brightgreen.svg" alt="SPARK Proved"></td>
+<td><img src="https://img.shields.io/badge/SPARK-Proved-green.svg" alt="SPARK Proved"></td>
 </tr>
 <tr>
 <td><strong>Scope</strong></td>
@@ -50,11 +78,11 @@ make spark-check    # Run SPARK legality verification
 make spark-prove    # Run full SPARK proof verification
 ```
 
-### Verified Packages
+### SPARK Coverage
 
 | Package | SPARK_Mode | Description |
 |---------|-----------|-------------|
-| `Functional.Result` | On | Result[T,E] monad (33 operations) |
+| `Functional.Result` | On | Result[T,E] monad (30 operations) |
 | `Functional.Option` | On | Option[T] monad (25 operations) |
 | `Functional.Either` | On | Either[L,R] type (20 operations) |
 | `Functional.Version` | On | Version information |
@@ -71,41 +99,6 @@ Since SPARK only analyzes instantiated generics (not generic templates), the lib
 - **Helper function verification**: All predicates and transformers formally proven overflow-safe
 - **High proof rate**: See [CHANGELOG](CHANGELOG.md) for current statistics
 
-## Features
-
-### Core Types (85+ operations)
-
-| Type | Operations | Purpose |
-|------|------------|---------|
-| **Result[T,E]** | 33 | Success/failure with typed errors |
-| **Option[T]** | 25 | Optional values (presence/absence) |
-| **Either[L,R]** | 20 | Disjoint unions (one of two types) |
-| **Try** | 7 | Exception-to-functional bridges |
-| **Scoped** | 2 | RAII resource guards |
-
-### SPARK Formal Verification
-
-- **SPARK_Mode => On** for Option, Result, Either, Version (formally verifiable)
-- **SPARK_Mode => Off** for Try only (exception boundary, by design)
-- **Postconditions** on all transform operations for prover assistance
-- **Preconditions** on all extractors preventing invalid access
-
-### Embedded Systems Ready
-
-- **Preelaborate/Pure** categorization on all packages
-- **Zero heap allocation** - Stack-based discriminated records only
-- **No controlled types** - No finalization overhead
-- **No tasking dependencies** - Ravenscar profile compatible
-- **Bounded memory** - Fixed-size structures
-- **No OS dependencies** - Pure Ada 2022
-
-### Production Quality
-
-- **Comprehensive test coverage** (90%+ code coverage)
-- **Zero dependencies** - Ada 2022 standard library only
-- **Comprehensive contracts** - Pre/Post conditions throughout
-- **Cross-platform** - POSIX and Windows tested
-
 ## Quick Start
 
 ### Installation
@@ -114,7 +107,7 @@ Add to your `alire.toml`:
 
 ```toml
 [[depends-on]]
-functional = "^3.0.0"
+functional = "^4.1.0"
 ```
 
 Then build:
@@ -202,26 +195,42 @@ Result := Str_Int.Fold (E, On_String'Access, On_Integer'Access);
 
 ### Try - Exception Boundaries
 
+Use `Map_To_Result_With_Param` (recommended) for declarative exception mapping:
+
 ```ada
-with Functional.Try;
+with Functional.Try.Map_To_Result_With_Param;
+
+package Try_Read is new Functional.Try.Map_To_Result_With_Param
+  (Error_Kind_Type    => Error_Kind,
+   Param_Type         => String,
+   Result_Type        => IO_Result.Result,
+   Make_Error         => Make_Error,
+   Default_Error_Kind => Internal_Error,
+   Action             => Read_File_Raw);
 
---  Bridge exception-based code to Result
-function Safe_Parse is new Functional.Try.Try_To_Functional_Result
-  (T => Integer, E => Error, Result_Pkg => Int_Result,
-   Map_Exception => To_Error, Action => Integer'Value);
+Mappings : constant Try_Read.Mapping_Array :=
+  [(Name_Error'Identity, Not_Found),
+   (Use_Error'Identity,  Permission_Error)];
 
-R := Safe_Parse;  --  Never raises, returns Result
+Result := Try_Read.Run (File_Path, Mappings);
+```
+
+Use `Try_To_Option_With_Param` for probe operations:
+
+```ada
+--  Returns None on any exception, then use Unwrap_Or
+Exists := Bool_Option.Unwrap_Or (Try_Is_TZif (Path), False);
 ```
 
 ## API Reference
 
-### Result<T,E> (33 operations)
+### Result<T,E> (30 operations)
 
 | Category | Operations |
 |----------|------------|
 | **Constructors** | `Ok`, `New_Error`, `From_Error` |
 | **Predicates** | `Is_Ok`, `Is_Error`, `Is_Ok_And`, `Is_Error_And`, `Is_Ok_Or`, `Is_Error_Or`, `Contains` |
-| **Extractors** | `Value`, `Error_Info` |
+| **Extractors** | `Value`, `Error` |
 | **Defaults** | `Unwrap_Or`, `Unwrap_Or_With` |
 | **Transforms** | `Map`, `Map_Or`, `Map_Or_Else`, `And_Then`, `And_Then_Into`, `Map_Error`, `Bimap`, `Zip_With`, `Flatten`, `To_Option` |
 | **Recovery** | `Fallback`, `Fallback_With`, `Recover`, `Recover_With` |
@@ -255,17 +264,16 @@ R := Safe_Parse;  --  Never raises, returns Result
 | **Conversion** | `To_Option`, `To_Result` |
 | **Operators** | `"="` (Contains) |
 
-### Try Module (7 functions)
+### Try Module (6 functions + child packages)
 
 | Function | Purpose |
 |----------|---------|
-| `Try_To_Result` | General bridge for any Result type |
-| `Try_To_Functional_Result` | Convenience for Functional.Result |
 | `Try_To_Functional_Option` | Convenience for Functional.Option |
-| `Try_To_Result_With_Param` | Parameterized Result bridge |
 | `Try_To_Option_With_Param` | Parameterized Option bridge |
 | `Map_To_Result` | Declarative exception mapping tables |
 | `Map_To_Result_With_Param` | Parameterized declarative mapping |
+| `Try_To_Result` | General bridge (deprecated) |
+| `Try_To_Functional_Result` | Convenience for Functional.Result (deprecated) |
 
 ### Scoped Module (2 generic packages)
 
@@ -287,24 +295,18 @@ make test-unit
 make test-coverage
 ```
 
-**Results:** 269 tests passing (Result: 84, Option: 65, Either: 58, Try: 14, Try_Option: 6, Scoped: 11, Map_To_Result: 31)
+**Results:** All tests passing. See [CHANGELOG](CHANGELOG.md) for current counts.
 
 ## Documentation
 
-- **[Cheatsheet](docs/guides/cheatsheet.md)** - All 87 operations at a glance
+- **[Cheatsheet](docs/guides/cheatsheet.md)** - All operations at a glance
 - **[User Guide](docs/guides/user_guide.md)** - Design philosophy, SPARK, embedded, best practices
 - **[Quick Start](docs/quick_start.md)** - Get started in minutes
 - **[SRS](docs/formal/software_requirements_specification.md)** - Requirements specification
 - **[SDS](docs/formal/software_design_specification.md)** - Design specification
 - **[STG](docs/formal/software_test_guide.md)** - Test guide
 - **[CHANGELOG](CHANGELOG.md)** - Release history
 
-## Code Standards
-
-This project follows:
-- **Ada Agent** (`~/.claude/agents/ada.md`)
-- **Functional Agent** (`~/.claude/agents/functional.md`)
-
 ## Submodule Management
 
 ```bash
@@ -313,6 +315,12 @@ make submodule-update    # Pull latest
 make submodule-status    # Check commits
 ```
 
+## Code Standards
+
+This project follows:
+- **Ada Agent** (`~/.claude/agents/ada.md`) - Ada 2022 standards
+- **Functional Agent** (`~/.claude/agents/functional.md`) - Result/Option/Either patterns
+
 ## Contributing
 
 This project is not open to external contributions at this time.
@@ -344,14 +352,14 @@ A Bit of Help, Inc.
 
 ## Project Status
 
-**Status**: Production Ready (v4.0.0)
-
-- ✅ Result[T,E] - 33 operations
-- ✅ Option[T] - 25 operations
-- ✅ Either[L,R] - 20 operations
-- ✅ Try module - 7 exception bridges
-- ✅ Scoped module - 2 RAII guard packages
-- ✅ SPARK compatible (Option, Result, Either, Version)
-- ✅ Comprehensive test coverage (90%+)
-- ✅ Zero external dependencies
-- ✅ Cross-platform (POSIX, Windows)
+**Status**: Production Ready (v4.1.0)
+
+- [x] Result[T,E] - 30 operations
+- [x] Option[T] - 25 operations
+- [x] Either[L,R] - 20 operations
+- [x] Try module - 6 functions + child packages
+- [x] Scoped module - 2 RAII guard packages
+- [x] SPARK compatible (see CHANGELOG for proof stats)
+- [x] Comprehensive test coverage (see CHANGELOG)
+- [x] Zero external dependencies
+- [x] Cross-platform (POSIX, Windows)