docs: replace magic strings with strong-typed references in all Option<T>/Fin<T> examples

Author: MPCoreDeveloper

docs/FUNCTIONAL_NULL_SAFETY.md

@@ -100,13 +100,18 @@ if (rows != null && rows.Count > 0)
 #### Functional (`Option<T>`) — Safe
 
 ```csharp
-// One expression. Compiler ensures you handle absence. Zero exceptions possible.
-var email = (await fdb.GetByIdAsync<UserDto>("Users", 99))
+// Strong-typed table reference and named constants — no magic strings.
+// Compiler ensures you handle absence. Zero exceptions possible.
+var email = (await fdb.GetByIdAsync<UserDto>(Tables.Users, userId))
     .Map(u => u.Email)
-    .Bind(e => string.IsNullOrEmpty(e) ? Option<string>.None : Option<string>.Some(e))
-    .IfNone("no-email");
+    .Bind(Option.FromNullOrEmpty)       // built-in helper, no ternary
+    .IfNone(Defaults.NoEmail);          // named constant, not a magic string
 ```
 
+> **Best practice:** Always use strongly-typed table references (e.g., `Tables.Users`) and named
+> constants (e.g., `Defaults.NoEmail`) instead of raw strings. `Option<T>` composes cleanly with
+> either approach — but strong typing eliminates the "magic string" class of bugs entirely.
+
 #### Error Handling: `Fin<T>` vs Try/Catch
 
 ```csharp
@@ -121,7 +126,7 @@ catch (Exception ex)
 }
 
 // Functional — errors as values
-var result = await fdb.InsertAsync("NonExistent", dto);
+var result = await fdb.InsertAsync(Tables.Orders, dto);
 result.Match(
     Succ: _ => Log("ok"),
     Fail: err => Log(err.Message)); // Zero-cost: no exception thrown
@@ -193,7 +198,7 @@ foreach (var row in rows)
 {
     var email = row
         .Map(u => u.Email)
-        .IfNone("no-email");
+        .IfNone(Defaults.NoEmail);
 
     Console.WriteLine(email);
 }

docs/NULLABLE_VS_OPTIONAL_REBUTTAL.md

@@ -44,9 +44,10 @@ The statement *"runtime data semantics cannot always be fully proven at compile
 
 ## "But Your Example Is Full of Magic Strings"
 
-A fair critique of the `Option<T>` showcase code:
+A fair critique of an earlier version of the `Option<T>` showcase code:
 
 ```csharp
+// ⚠️ Original example (now updated in docs) — shown here for context
 var email = (await fdb.GetByIdAsync<UserDto>("Users", 99))
     .Map(u => u.Email)
     .Bind(e => string.IsNullOrEmpty(e) ? Option<string>.None : Option<string>.Some(e))
@@ -55,7 +56,7 @@ var email = (await fdb.GetByIdAsync<UserDto>("Users", 99))
 
 > *"What if `"Users"` should be `"User"`? What about `"no-email"` — is that a prefix convention? String-based keys, magic strings, ternaries for the logic you're promoting... This is just runtime errors with extra steps."*
 
-**This critique is valid — and it targets the example, not the concept.** Let's separate the two.
+**This critique was valid — and we've since updated all documentation examples.** But the deeper point is worth addressing: the complaint targets the *example*, not the *concept*. Let's separate the two.
 
 ### What the critique actually proves
 

src/SharpCoreDB.Functional/README.md

@@ -87,9 +87,9 @@ Source: `tests/SharpCoreDB.Functional.Tests/FunctionalSqlSyntaxTests.cs`
 var dbf = database.Functional();
 
 var result = await dbf
-    .GetByIdAsync<User>("Users", 42, cancellationToken: ct)
+    .GetByIdAsync<User>(Tables.Users, userId, cancellationToken: ct)
     .Map(opt => opt.Map(user => user with { LastSeenUtc = DateTime.UtcNow }))
-    .Map(opt => opt.ToFin("User not found"));
+    .Map(opt => opt.ToFin(Errors.UserNotFound));
 
 result.Match(
     Succ: _ => Console.WriteLine("updated"),