docs: align Projectable pages with post-facelift conventions

- Replace Unicode em-dashes with double-hyphens to match reference/recipe style
- Rename "Further reading" → "See Also" in the projection-middleware recipe
- Update UseMemberBody migration row to mention both replacement options
- Add MongoDB BSON unmapping convention note

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: koenbeuk

docs/guide/integrations/mongodb.md

@@ -43,6 +43,12 @@ db.Customers
 
 No custom MQL is emitted — MongoDB's own translator does all the heavy lifting after ExpressiveSharp has normalized the tree.
 
+## `[Expressive]` Properties Are Unmapped from BSON
+
+ExpressiveSharp registers a MongoDB `IClassMapConvention` that unmaps every `[Expressive]`-decorated property from the BSON class map, so the property's backing field is not persisted to documents. This matters most for [Projectable properties](../../reference/projectable-properties), which have a writable `init` accessor and would otherwise be serialized as a real BSON field.
+
+The convention is registered automatically the first time you construct an `ExpressiveMongoCollection<T>` or call `.AsExpressive()` on a collection. No opt-in is required.
+
 ## Async Methods
 
 All MongoDB async LINQ methods (from `MongoQueryable`) work with modern syntax via interceptors. They are stubs on `IExpressiveMongoQueryable<T>` that forward to their `MongoQueryable` counterparts:

docs/guide/migration-from-projectables.md

@@ -122,7 +122,7 @@ Both the old `Ignore` and `Rewrite` behaviors converge to the same result in Exp
 
 | Old Property | Migration |
 |---|---|
-| `UseMemberBody = "SomeMethod"` | Replace with `[ExpressiveFor]`. See [Migrating UseMemberBody](#migrating-usememberbody) below. |
+| `UseMemberBody = "SomeMethod"` | Replace with `[Expressive(Projectable = true)]` or `[ExpressiveFor]`. See [Migrating UseMemberBody](#migrating-usememberbody) below. |
 | `AllowBlockBody = true` | Keep -- block bodies remain opt-in. Set per-member or globally via `Expressive_AllowBlockBody` MSBuild property. |
 | `ExpandEnumMethods = true` | Remove -- enum method expansion is enabled by default. |
 | `CompatibilityMode.Full / .Limited` | Remove -- only the full approach exists. |

docs/recipes/projection-middleware.md

@@ -1,6 +1,6 @@
 # Computed Properties in Projection Middleware
 
-If your computed property returns an empty value — or is silently dropped from the response — when consumed by **HotChocolate**, **AutoMapper's `ProjectTo`**, **Mapperly's projection mode**, or any other framework that emits `Select(src => new Entity { Member = src.Member, ... })` over your entity type, this recipe is the fix.
+If your computed property returns an empty value -- or is silently dropped from the response -- when consumed by **HotChocolate**, **AutoMapper's `ProjectTo`**, **Mapperly's projection mode**, or any other framework that emits `Select(src => new Entity { Member = src.Member, ... })` over your entity type, this recipe is the fix.
 
 ## Why plain `[Expressive]` isn't enough
 
@@ -10,7 +10,7 @@ HotChocolate's `[UseProjection]` middleware (and similar mechanisms in other lib
 query { users { fullName } }
 ```
 
-HotChocolate inspects the `User.FullName` property, finds it is **read-only** (no setter), and silently drops it from the projection. The generated SQL is `SELECT 1 FROM Users` — nothing is fetched. At materialization time, HC constructs fresh `User` instances with all fields at their defaults (`FirstName = ""`, `LastName = ""`), calls the `FullName` getter, and the formula returns `", "`. The response looks successful but the data is wrong.
+HotChocolate inspects the `User.FullName` property, finds it is **read-only** (no setter), and silently drops it from the projection. The generated SQL is `SELECT 1 FROM Users` -- nothing is fetched. At materialization time, HC constructs fresh `User` instances with all fields at their defaults (`FirstName = ""`, `LastName = ""`), calls the `FullName` getter, and the formula returns `", "`. The response looks successful but the data is wrong.
 
 The same mechanism affects AutoMapper's `ProjectTo<Entity>`, Mapperly's generated projections, and any hand-rolled `Select(u => new User { ... })` that projects into the source type itself.
 
@@ -23,7 +23,7 @@ Turning on `Projectable = true` makes the property writable (so the projection m
 
 ## Before and after
 
-**Before** — plain `[Expressive]` on a read-only property. Broken for projection middleware.
+**Before** -- plain `[Expressive]` on a read-only property. Broken for projection middleware.
 
 ```csharp
 public class User
@@ -36,10 +36,10 @@ public class User
 }
 ```
 
-GraphQL response: `{ "users": [{ "fullName": ", " }, { "fullName": ", " }] }` — wrong.
-SQL emitted: `SELECT 1 FROM Users` — nothing fetched.
+GraphQL response: `{ "users": [{ "fullName": ", " }, { "fullName": ", " }] }` -- wrong.
+SQL emitted: `SELECT 1 FROM Users` -- nothing fetched.
 
-**After** — `Projectable = true`.
+**After** -- `Projectable = true`.
 
 ```csharp
 public class User
@@ -56,8 +56,8 @@ public class User
 }
 ```
 
-GraphQL response: `{ "users": [{ "fullName": "Lovelace, Ada" }, { "fullName": "Turing, Alan" }] }` — correct.
-SQL emitted: `SELECT u.LastName || ', ' || u.FirstName AS "FullName" FROM Users u` — formula pushed into SQL.
+GraphQL response: `{ "users": [{ "fullName": "Lovelace, Ada" }, { "fullName": "Turing, Alan" }] }` -- correct.
+SQL emitted: `SELECT u.LastName || ', ' || u.FirstName AS "FullName" FROM Users u` -- formula pushed into SQL.
 
 No HC glue code is required beyond the normal `.UseExpressives()` on the DbContext options. The convention auto-ignores the property in EF's model (so no `FullName` column is created), and the projection rewrite happens automatically when the query compiler intercepts.
 
@@ -118,7 +118,7 @@ SELECT (u.LastName || ', ' || u.FirstName) || ' <' || u.Email || '>' AS "Display
 FROM Users u
 ```
 
-Notice how `DisplayLabel` composes with `FullName` (which is itself Projectable) — the transitive rewrite is handled automatically by the expression resolver.
+Notice how `DisplayLabel` composes with `FullName` (which is itself Projectable) -- the transitive rewrite is handled automatically by the expression resolver.
 
 ## Full AutoMapper example
 
@@ -161,8 +161,9 @@ internal static class UserMappings
 
 Both approaches produce the same SQL and work identically with HotChocolate / AutoMapper. The `Projectable` form is more concise and keeps the formula on the property itself; the `ExpressiveFor` form is explicit about the separation. See the [migration guide](../guide/migration-from-projectables) for a side-by-side comparison.
 
-## Further reading
+## See Also
 
-- [Projectable Properties reference](../reference/projectable-properties) — full reference including restrictions and runtime semantics.
-- [`[ExpressiveFor]` Mapping](../reference/expressive-for) — alternative pattern for scenarios where you can't modify the entity type.
-- [Migrating from Projectables](../guide/migration-from-projectables) — side-by-side migration paths.
+- [Projectable Properties](../reference/projectable-properties) -- full reference including restrictions and runtime semantics
+- [`[ExpressiveFor]` Mapping](../reference/expressive-for) -- alternative pattern for scenarios where you can't modify the entity type
+- [Migrating from Projectables](../guide/migration-from-projectables) -- side-by-side migration paths for `UseMemberBody`
+- [Computed Entity Properties](./computed-properties) -- plain `[Expressive]` computed values for DTO projections

docs/reference/projectable-properties.md

@@ -24,9 +24,9 @@ db.Users.Select(src => new User { FullName = src.FullName });
 
 What happens next, silently:
 
-- HotChocolate checks whether `FullName` is writable (it looks at `PropertyInfo.CanWrite`). It isn't — getter only.
+- HotChocolate checks whether `FullName` is writable (it looks at `PropertyInfo.CanWrite`). It isn't -- getter only.
 - HC **drops** the `FullName = src.FullName` binding from the projection. No warning, no error.
-- EF emits `SELECT 1 FROM Users` — nothing is fetched because the projection is empty.
+- EF emits `SELECT 1 FROM Users` -- nothing is fetched because the projection is empty.
 - HC constructs `User` instances with all fields at their defaults (`FirstName = ""`, `LastName = ""`), then reads `user.FullName`.
 - The getter evaluates `"" + ", " + ""` and returns `", "`.
 - Your GraphQL response is `{ "users": [{ "fullName": ", " }, { "fullName": ", " }] }`.
@@ -69,57 +69,57 @@ A Projectable property has two states, distinguished by the backing field's valu
 | **Not materialized** | `null` | Evaluates the formula from dependencies | In-memory construction (`new User { FirstName = "Ada" }`) |
 | **Materialized** | non-null | The stored value | EF / HC wrote to `init` after computing the formula in SQL |
 
-The `??` operator picks between the two. In both cases, reading `user.FullName` returns the correct value — the difference is only *where* the value came from.
+The `??` operator picks between the two. In both cases, reading `user.FullName` returns the correct value -- the difference is only *where* the value came from.
 
 ```csharp
-// State 1 — in memory, field is null, formula fires
+// State 1 -- in memory, field is null, formula fires
 var u1 = new User { FirstName = "Ada", LastName = "Lovelace" };
 u1.FullName;  // "Lovelace, Ada" (computed)
 
-// State 2 — after SQL materialization, stored value wins
+// State 2 -- after SQL materialization, stored value wins
 var u2 = await db.Users.FirstAsync();
 u2.FullName;  // "Lovelace, Ada" (stored, originally computed server-side)
 
 // Mutation behavior differs between states
-u1.FirstName = "Augusta"; u1.FullName;  // "Lovelace, Augusta" — formula reruns
-u2.FirstName = "Augusta"; u2.FullName;  // "Lovelace, Ada" — stored value wins
+u1.FirstName = "Augusta"; u1.FullName;  // "Lovelace, Augusta" -- formula reruns
+u2.FirstName = "Augusta"; u2.FullName;  // "Lovelace, Ada" -- stored value wins
 ```
 
 The mutation-after-materialization behavior mirrors how EF's change tracking works: once a value is loaded, it stays put until something deliberately writes to it.
 
 ### Gotcha: stale values after dependency mutation
 
-Once the backing field has been written — which happens every time the property is materialized from a SQL projection — mutating the formula's dependencies does **not** update the stored value. This can surprise users coming from [EFCore.Projectables](https://github.com/koenbeuk/EntityFrameworkCore.Projectables), where the formula always reruns on every read.
+Once the backing field has been written -- which happens every time the property is materialized from a SQL projection -- mutating the formula's dependencies does **not** update the stored value. This can surprise users coming from [EFCore.Projectables](https://github.com/koenbeuk/EntityFrameworkCore.Projectables), where the formula always reruns on every read.
 
 ```csharp
-// Loaded via EF/HC projection that included FullName — `field` is now populated.
+// Loaded via EF/HC projection that included FullName -- `field` is now populated.
 var user = await db.Users.FirstAsync(u => u.Id == 1);
 user.FullName;  // "Lovelace, Ada"
 
 user.FirstName = "Augusta";
-user.FullName;  // Still "Lovelace, Ada" — the stored value wins, formula is not rerun.
+user.FullName;  // Still "Lovelace, Ada" -- the stored value wins, formula is not rerun.
 ```
 
-**Why this behaves this way**: the stored value is authoritative. ExpressiveSharp treats a materialized property the same way EF treats any loaded property — if you want a change reflected, you write it explicitly. This keeps the two states (in-memory-computed vs. SQL-materialized) from silently disagreeing with each other.
+**Why this behaves this way**: the stored value is authoritative. ExpressiveSharp treats a materialized property the same way EF treats any loaded property -- if you want a change reflected, you write it explicitly. This keeps the two states (in-memory-computed vs. SQL-materialized) from silently disagreeing with each other.
 
 **The staleness applies only to materialized instances.** Two cases where the formula still fires on every read:
 
-- **Constructed in memory** (`new User { FirstName = "Ada", LastName = "Lovelace" }`) — `field` is null, mutations to `FirstName`/`LastName` propagate as you'd expect.
-- **Loaded without projecting the property** (e.g. `db.Users.FirstAsync()` without a `Select` that includes `FullName`) — the `init` accessor was never called, so `field` is still null.
+- **Constructed in memory** (`new User { FirstName = "Ada", LastName = "Lovelace" }`) -- `field` is null, mutations to `FirstName`/`LastName` propagate as you'd expect.
+- **Loaded without projecting the property** (e.g. `db.Users.FirstAsync()` without a `Select` that includes `FullName`) -- the `init` accessor was never called, so `field` is still null.
 
 **If you need the formula to rerun after dependency mutation on a materialized instance**, you have a few options:
 
-1. **Re-fetch the entity** — let EF re-run the query with the new values.
-2. **Use plain `[Expressive]` with a DTO projection** — if you're not going through projection middleware, a read-only `[Expressive]` on a DTO type is simpler and has no staleness.
-3. **Expose a reset method** — for example `public void ResetFullName() { typeof(User).GetField(...).SetValue(this, null); }` to null out the backing field and let the formula fire again on the next read. This is rarely worth the complexity; options 1 and 2 cover the common cases.
+1. **Re-fetch the entity** -- let EF re-run the query with the new values.
+2. **Use plain `[Expressive]` with a DTO projection** -- if you're not going through projection middleware, a read-only `[Expressive]` on a DTO type is simpler and has no staleness.
+3. **Expose a reset method** -- for example `public void ResetFullName() { typeof(User).GetField(...).SetValue(this, null); }` to null out the backing field and let the formula fire again on the next read. This is rarely worth the complexity; options 1 and 2 cover the common cases.
 
 ## When to use it vs. plain `[Expressive]`
 
 Only turn `Projectable = true` on when you actually have the problem above. The quick test:
 
 > *Does anything in my stack generate `Select(src => new Entity { ... })` over this entity type?*
 
-If you can answer yes (HotChocolate with `[UseProjection]`, AutoMapper `ProjectTo<SameType>`, Mapperly projections, hand-rolled patterns), the property needs to be Projectable. If not — if you only ever project into DTOs or read the property directly — plain `[Expressive]` is simpler and has no restrictions.
+If you can answer yes (HotChocolate with `[UseProjection]`, AutoMapper `ProjectTo<SameType>`, Mapperly projections, hand-rolled patterns), the property needs to be Projectable. If not -- if you only ever project into DTOs or read the property directly -- plain `[Expressive]` is simpler and has no restrictions.
 
 ## Syntax
 
@@ -134,7 +134,7 @@ public string FullName
 }
 ```
 
-- **Get accessor**: must be `=> <backingField> ?? (<formula>)`. The generator matches this exact shape — ternaries (`a != null ? a : b`), block bodies with `if`/`return`, and other forms are rejected with [EXP0022](./diagnostics#exp0022).
+- **Get accessor**: must be `=> <backingField> ?? (<formula>)`. The generator matches this exact shape -- ternaries (`a != null ? a : b`), block bodies with `if`/`return`, and other forms are rejected with [EXP0022](./diagnostics#exp0022).
 - **Init/set accessor**: must be `=> <backingField> = value`. Transformations like `value?.Trim()` are rejected with [EXP0023](./diagnostics#exp0023).
 - **Class does not need to be `partial`.** **Property does not need to be `partial`.**
 
@@ -143,15 +143,15 @@ public string FullName
 Either the C# 14 `field` keyword (preferred) or a manually declared private nullable field works:
 
 ```csharp
-// Option A — `field` keyword (C# 14+)
+// Option A -- `field` keyword (C# 14+)
 [Expressive(Projectable = true)]
 public string FullName
 {
     get => field ?? (LastName + ", " + FirstName);
     init => field = value;
 }
 
-// Option B — manual backing field
+// Option B -- manual backing field
 private string? _fullName;
 
 [Expressive(Projectable = true)]
@@ -168,8 +168,8 @@ The manual field must be **private**, **on the same type as the property**, and
 
 Both are accepted. Pick based on whether callers should be able to override the stored value after construction:
 
-- `init` — value can only be set through object initializers (EF, HC) or the constructor. Recommended default.
-- `set` — callers can also assign `user.FullName = "..."` directly. Useful if you want to support manual overrides.
+- `init` -- value can only be set through object initializers (EF, HC) or the constructor. Recommended default.
+- `set` -- callers can also assign `user.FullName = "..."` directly. Useful if you want to support manual overrides.
 
 ## Restrictions
 
@@ -198,7 +198,7 @@ No `[NotMapped]` annotation or manual `modelBuilder.Ignore(...)` call is require
 
 ## Comparison with `[ExpressiveFor]`
 
-`[ExpressiveFor]` is the verbose alternative — the formula lives in a separate static stub instead of on the property:
+`[ExpressiveFor]` is the verbose alternative -- the formula lives in a separate static stub instead of on the property:
 
 ```csharp
 public class User
@@ -215,13 +215,13 @@ internal static class UserMappings
 
 Both produce identical SQL and both work with HC/AutoMapper. Pick based on preference:
 
-- **`[Expressive(Projectable = true)]`** — formula lives on the property. Single declaration site. Recommended default.
-- **`[ExpressiveFor]`** — formula in a separate class. More explicit. Required when you can't modify the entity type (third-party code) or need to map cross-type.
+- **`[Expressive(Projectable = true)]`** -- formula lives on the property. Single declaration site. Recommended default.
+- **`[ExpressiveFor]`** -- formula in a separate class. More explicit. Required when you can't modify the entity type (third-party code) or need to map cross-type.
 
 See the [migration guide](../guide/migration-from-projectables#migrating-usememberbody) for side-by-side examples.
 
 ## Further reading
 
-- [Projection Middleware recipe](../recipes/projection-middleware) — end-to-end HotChocolate + AutoMapper examples.
-- [`[Expressive]` Attribute reference](./expressive-attribute) — base attribute.
-- [`[ExpressiveFor]` reference](./expressive-for) — verbose alternative.
+- [Projection Middleware recipe](../recipes/projection-middleware) -- end-to-end HotChocolate + AutoMapper examples.
+- [`[Expressive]` Attribute reference](./expressive-attribute) -- base attribute.
+- [`[ExpressiveFor]` reference](./expressive-for) -- verbose alternative.