Add enterprise docs structure and include pending core maintenance updates.

docs/features/README.md

@@ -0,0 +1,10 @@
+# Feature Inventory
+
+The following documents are the canonical reference for major CBDD capabilities:
+
+- [Storage and transactions](storage-transactions.md)
+- [Query and indexing](query-and-indexing.md)
+- [Vector search](vector-search.md)
+- [Geospatial search](geospatial-search.md)
+- [Change data capture](change-data-capture.md)
+- [Source-generated mapping](source-generated-mapping.md)

docs/features/change-data-capture.md

@@ -0,0 +1,61 @@
+# Change Data Capture
+
+## Purpose And Business Outcome
+
+Expose transactional change events so consumers can react to committed inserts, updates, and deletes.
+
+## Scope And Non-Goals
+
+Scope:
+- Collection-level change stream subscriptions
+- Event publication after successful commit
+
+Non-goals:
+- Cross-process event transport guarantees
+- External message broker delivery semantics
+
+## User And System Workflows
+
+1. Consumer subscribes to a collection change stream.
+2. Application performs data mutations.
+3. On commit, CDC publishes events to active subscribers.
+4. Subscriber handlers process entity and metadata payloads.
+
+## Interfaces And APIs
+
+- `Watch(...)` collection API
+- `ChangeStreamObservable`
+- `ChangeStreamDispatcher`
+- `ChangeStreamEvent`
+
+## Permissions And Data Handling
+
+- CDC payloads can include document identifiers and entity data.
+- Restrict subscription access to trusted application components.
+
+## Dependencies And Failure Modes
+
+Dependencies:
+- Transaction commit lifecycle
+- Subscriber channel health
+
+Failure modes:
+- Subscriber backpressure or handler exceptions
+- Event handling assumptions that conflict with rollback behavior
+
+## Monitoring, Alerts, And Troubleshooting
+
+- Review CDC behavior in integration and scalability tests.
+- Follow [`../runbook.md`](../runbook.md) for incident response.
+- Follow [`../security.md`](../security.md) for event payload handling controls.
+- Use [`../troubleshooting.md`](../troubleshooting.md) for diagnosis guidance.
+
+## Rollout And Change Considerations
+
+- Behavioral CDC changes require explicit release-note callouts.
+- Maintain compatibility expectations for event payload shape.
+
+## Validation Guidance
+
+- Run `CdcTests` and `CdcScalabilityTests` before release.
+- Validate commit-only emission behavior in regression tests.

docs/features/geospatial-search.md

@@ -0,0 +1,60 @@
+# Geospatial Search
+
+## Purpose And Business Outcome
+
+Support location-aware queries such as nearest-neighbor and bounding-box lookups for geospatial workloads.
+
+## Scope And Non-Goals
+
+Scope:
+- Spatial index configuration
+- Proximity and bounding-box query operations
+
+Non-goals:
+- Full GIS projection transformations
+- External map tile services
+
+## User And System Workflows
+
+1. Consumer configures spatial index for coordinate fields.
+2. Coordinates are serialized and stored with entity payloads.
+3. Query path evaluates `Near` or `Within` predicates.
+4. Engine returns matching entities.
+
+## Interfaces And APIs
+
+- Spatial index APIs in model configuration
+- Query helpers under `GeoSpatialExtensions`
+- Index implementation in `RTreeIndex`
+
+## Permissions And Data Handling
+
+- Geolocation data may be regulated or privacy-sensitive.
+- Apply least-privilege access and retention limits.
+
+## Dependencies And Failure Modes
+
+Dependencies:
+- Correct coordinate format and units
+- Spatial index consistency
+
+Failure modes:
+- Invalid coordinate values
+- Unexpected results from bounding definitions or radius units
+
+## Monitoring, Alerts, And Troubleshooting
+
+- Validate geospatial paths through dedicated stress and correctness tests.
+- Use [`../runbook.md`](../runbook.md) for escalation.
+- Follow [`../security.md`](../security.md) for geolocation data protection controls.
+- Use [`../troubleshooting.md`](../troubleshooting.md#query-and-index-issues) for issue resolution.
+
+## Rollout And Change Considerations
+
+- Document coordinate and unit assumptions in release notes when behavior changes.
+- Validate backward compatibility for persisted spatial index pages.
+
+## Validation Guidance
+
+- Run `GeospatialTests` and `GeospatialStressTests` before release.
+- Include representative proximity/bounding queries in smoke checks.

docs/features/query-and-indexing.md

@@ -0,0 +1,62 @@
+# Query And Indexing
+
+## Purpose And Business Outcome
+
+Deliver predictable query correctness and performance using expression translation with index-aware execution.
+
+## Scope And Non-Goals
+
+Scope:
+- LINQ query translation
+- Primary and secondary index usage
+- Scan fallback where index optimization is not applicable
+
+Non-goals:
+- Full SQL compatibility
+- Distributed query federation
+
+## User And System Workflows
+
+1. Consumer submits LINQ expression.
+2. Query planner evaluates index opportunities.
+3. Engine executes index-backed or scan path.
+4. Results are materialized to consumer entities.
+
+## Interfaces And APIs
+
+- `AsQueryable()` and query provider components
+- `CollectionIndexManager`
+- Index implementations under `src/CBDD.Core/Indexing`
+
+## Permissions And Data Handling
+
+- Query access follows host application authorization policy.
+- Indexed data inherits the same sensitivity classification as source payloads.
+
+## Dependencies And Failure Modes
+
+Dependencies:
+- Valid index metadata and storage consistency
+- Expression visitor correctness
+
+Failure modes:
+- Incorrect predicate translation
+- Missing/ineffective indexes
+- Performance regressions due to scan-heavy paths
+
+## Monitoring, Alerts, And Troubleshooting
+
+- Track query-related regressions in automated tests.
+- Use [`../runbook.md`](../runbook.md) for incident handling.
+- Follow [`../security.md`](../security.md) for sensitive data and access constraints.
+- Use [`../troubleshooting.md`](../troubleshooting.md#query-and-index-issues) for remediation.
+
+## Rollout And Change Considerations
+
+- Query planner/index behavior changes require benchmark comparison and regression coverage.
+- Document breaking semantics in release notes.
+
+## Validation Guidance
+
+- Run query, index, and optimizer test suites in `tests/CBDD.Tests`.
+- Confirm coverage gate with `bash scripts/coverage-check.sh`.

docs/features/source-generated-mapping.md

@@ -0,0 +1,61 @@
+# Source-Generated Mapping
+
+## Purpose And Business Outcome
+
+Generate compile-time mapping code to reduce runtime overhead and reflection risk for serialization paths.
+
+## Scope And Non-Goals
+
+Scope:
+- Entity metadata analysis
+- Mapper source generation
+- Collection initialization helpers
+
+Non-goals:
+- Runtime dynamic mapping for unknown schemas
+- Support for unsupported C# patterns outside generator design
+
+## User And System Workflows
+
+1. Consumer defines entities and context patterns.
+2. Build invokes source generator.
+3. Generated mapper code is compiled into target project.
+4. Runtime serialization path uses generated code.
+
+## Interfaces And APIs
+
+- Source generator project under `src/CBDD.SourceGenerators`
+- Attributes in BSON and data-annotation mapping surface
+- Generated initialization methods for context collections
+
+## Permissions And Data Handling
+
+- Generated code can expose field-level mapping behavior.
+- Repository write permissions should be limited to trusted contributors.
+
+## Dependencies And Failure Modes
+
+Dependencies:
+- Roslyn source generator execution during build
+- Entity schema conventions
+
+Failure modes:
+- Missing generation due to invalid entity declarations
+- Serialization mismatch caused by attribute/model changes
+
+## Monitoring, Alerts, And Troubleshooting
+
+- Monitor build output for generator diagnostics.
+- Use [`../runbook.md`](../runbook.md) for escalation.
+- Follow [`../security.md`](../security.md) for review and control expectations.
+- Use [`../troubleshooting.md`](../troubleshooting.md#source-generation-issues) for remediation steps.
+
+## Rollout And Change Considerations
+
+- Generator behavioral changes require broad regression tests across entities.
+- Document any new constraints or unsupported patterns in release notes.
+
+## Validation Guidance
+
+- Run source generator and serialization tests in `tests/CBDD.Tests`.
+- Validate mapper generation with clean `dotnet build` in CI.

docs/features/storage-transactions.md

@@ -0,0 +1,63 @@
+# Storage And Transactions
+
+## Purpose And Business Outcome
+
+Provide durable, ACID-compliant local persistence for embedded workloads that need consistent commit and recovery semantics.
+
+## Scope And Non-Goals
+
+Scope:
+- Page-based storage
+- Write-ahead logging
+- Transaction lifecycle and commit/rollback semantics
+
+Non-goals:
+- Distributed transactions
+- Multi-node replication
+
+## User And System Workflows
+
+1. Application writes through `DocumentDbContext`.
+2. Engine records WAL entries.
+3. Commit persists pages and marks transaction durable.
+4. Recovery replays WAL to restore committed state after restart.
+
+## Interfaces And APIs
+
+- `DocumentDbContext`
+- `Transaction` and `ITransaction`
+- `WriteAheadLog`
+- Storage engine modules under `src/CBDD.Core/Storage`
+
+## Permissions And Data Handling
+
+- Database files require host-managed filesystem access controls.
+- Transaction data should be treated as sensitive if payloads contain regulated information.
+
+## Dependencies And Failure Modes
+
+Dependencies:
+- Local filesystem I/O
+- WAL and page file consistency
+
+Failure modes:
+- Interrupted writes
+- Corrupted WAL entries
+- Invalid page metadata after unsafe process termination
+
+## Monitoring, Alerts, And Troubleshooting
+
+- Use CI/test failures and incident issues as primary signals.
+- Follow [`../runbook.md`](../runbook.md) for triage.
+- Follow [`../security.md`](../security.md) for data handling and control requirements.
+- Use [`../troubleshooting.md`](../troubleshooting.md#data-file-and-recovery-issues) for recovery issues.
+
+## Rollout And Change Considerations
+
+- Any storage format or WAL behavior change requires migration and rollback validation.
+- Release notes must document backward compatibility impact.
+
+## Validation Guidance
+
+- Run transaction and recovery tests in `tests/CBDD.Tests`.
+- Execute `dotnet test CBDD.slnx -c Release` before merge.

docs/features/vector-search.md

@@ -0,0 +1,60 @@
+# Vector Search
+
+## Purpose And Business Outcome
+
+Enable similarity search for embedding-driven workloads directly in embedded storage.
+
+## Scope And Non-Goals
+
+Scope:
+- Vector index configuration
+- Approximate nearest-neighbor query execution
+
+Non-goals:
+- External model training
+- Cross-database vector federation
+
+## User And System Workflows
+
+1. Consumer registers vector index for embedding field.
+2. Documents persist embeddings in collection payloads.
+3. Query issues vector search request with `k` nearest neighbors.
+4. Engine returns ranked matches.
+
+## Interfaces And APIs
+
+- Vector index configuration via model builder
+- Query extensions under `VectorSearchExtensions`
+- Index implementation in `VectorSearchIndex`
+
+## Permissions And Data Handling
+
+- Embeddings may contain sensitive semantic information.
+- Apply host-level access restrictions and retention controls.
+
+## Dependencies And Failure Modes
+
+Dependencies:
+- Correct embedding dimensionality
+- Index parameter tuning for workload
+
+Failure modes:
+- Dimension mismatch between data and query vectors
+- Poor recall due to incorrect index configuration
+
+## Monitoring, Alerts, And Troubleshooting
+
+- Validate vector query quality during release smoke checks.
+- Use [`../runbook.md`](../runbook.md) for incident handling.
+- Follow [`../security.md`](../security.md) for embedding-data handling controls.
+- Use [`../troubleshooting.md`](../troubleshooting.md#query-and-index-issues) for vector query remediation.
+
+## Rollout And Change Considerations
+
+- Treat vector index parameter changes as performance-sensitive releases.
+- Document compatibility impact for existing persisted indexes.
+
+## Validation Guidance
+
+- Run vector search tests in `tests/CBDD.Tests/VectorSearchTests.cs`.
+- Add benchmark runs for large-vector workloads before release.