Integrate deep-dive content into API docs and expand mapping

docs/stored-procedures.md

@@ -2,8 +2,6 @@
 
 Stored procedure support is available through `db.Procedures` when `DynamicDatabaseOptions.SupportStoredProcedures` is enabled.
 
-For an in-depth comparison with query syntax styles and advanced return-shape behavior, see [Syntax Deep Dive and Procedure Calls](syntax-and-procedures-deep-dive.md).
-
 ## Basic Invocation
 
 ```csharp
@@ -11,26 +9,7 @@ var scalar = db.Procedures.sp_Exp_Scalar();
 var scalarTyped = db.Procedures.sp_Exp_Scalar<int>();
 ```
 
-## Input, Output, Return Parameters
-
-Prefixes in argument names control parameter direction:
-
-- `out_` for output
-- `ret_` for return value
-- `both_` for input/output
-
-Example pattern:
-
-```csharp
-var res = db.Procedures.sp_Exp_SomeInputAndOutput<
-    string,
-    MyProcResult>(
-        Name: "G4g4r1n",
-        out_Result: new DynamicSchemaColumn { Size = 256 },
-        ret_Return: 0);
-```
-
-## Nested Procedure Names
+## Schema-Qualified Invocation
 
 Dynamic member chaining builds qualified names:
 
@@ -40,14 +19,82 @@ var res = db.Procedures.dbo.reporting.MyProc();
 
 This resolves to `dbo.reporting.MyProc`.
 
-## Result Mapping
+## Input, Output, Return, InputOutput Parameters
 
-If generic return types are provided, DynamORM attempts mapper-based projection into the target type.
+Prefixes in argument names control parameter direction:
 
-If output parameters are present, result payload is assembled from:
+- `out_` for output
+- `ret_` for return value
+- `both_` for input/output
 
-- main scalar/resultset-derived value
-- output values
-- optional return value
+Example:
 
-The behavior is implemented in `DynamORM/DynamicProcedureInvoker.cs` and documented in XML examples in `DynamORM/DynamicDatabase.cs`.
+```csharp
+dynamic res = db.Procedures.sp_Test_Scalar_In_Out(
+    inp: Guid.NewGuid(),
+    out_outp: Guid.Empty,
+    ret_Return: 0);
+```
+
+## Using `DynamicSchemaColumn` for Explicit Output Shape
+
+```csharp
+var res = db.Procedures.sp_Exp_SomeInputAndOutput<string, ProcResult>(
+    Name: "G4g4r1n",
+    out_Result: new DynamicSchemaColumn
+    {
+        Name = "Result",
+        Size = 256
+    },
+    ret_Return: 0);
+```
+
+## Using `DynamicColumn` for Direction + Value + Schema
+
+```csharp
+var res = db.Procedures.sp_WithInputOutput(
+    both_State: new DynamicColumn
+    {
+        ColumnName = "State",
+        ParameterDirection = ParameterDirection.InputOutput,
+        Value = "pending",
+        Schema = new DynamicSchemaColumn { Name = "State", Size = 32 }
+    });
+```
+
+## Result Shapes
+
+From `DynamicProcedureInvoker` behavior:
+
+- `T == IDataReader`: returns `CachedReader()` result.
+- `T == DataTable`: materializes via `ToDataTable(...)`.
+- `T == IEnumerable<object>`: dynamic row enumeration.
+- `T == IEnumerable<primitive>`: converts first column of each row.
+- `T == IEnumerable<class>`: maps rows via mapper cache.
+- `T == class`: maps structured result to a class.
+
+Examples:
+
+```csharp
+IDataReader rdr = db.Procedures.MyProc<IDataReader>();
+DataTable table = db.Procedures.MyProc<DataTable>();
+List<int> ids = db.Procedures.MyProc<List<int>>();
+List<User> users = db.Procedures.MyProc<List<User>>();
+User user = db.Procedures.MyProc<User>();
+```
+
+## Output and Return Value Aggregation
+
+When output and/or return values are used, DynamORM aggregates:
+
+- main result
+- output parameters
+- return value
+
+into a dynamic object or mapped class (if a target type is provided).
+
+## Notes
+
+- Enable `DynamicDatabaseOptions.SupportStoredProcedures` in options.
+- Prefix stripping is automatic in result keys (`out_Result` becomes `Result`).
+- Behavior is implemented in `DynamORM/DynamicProcedureInvoker.cs` and XML examples in `DynamORM/DynamicDatabase.cs`.