Epic: v6.0.0 — migration guide, changelog, docs, samples and release engineering #296

Discussion: #287 · Reliability work: #288 · Milestone: v6 · Architecture decisions: #308

Why v6 needs more than the fixes

v6 is the first major since the oracle suites started, and it breaks more than an API. The v6 milestone changes the on-disk index key format (#212, #234), and #288 changes defaults that cost time on every commit (#280 makes WalSyncMode.Full the default). A v5 user who upgrades needs to know, before they upgrade, which files v6 opens, what it rewrites on first open, how long that takes, and what answers differently afterwards.

Today they would have to work that out from the commit log. The changelog is generated by versionize (the 5.2.3 entry is empty), there is no migration guide, the docs at blitedb.com are hand-written Vue pages in a separate repository, and BLite.Website/CODE_SAMPLE_ANALYSIS.md already lists pages whose samples call APIs the core does not have (BLiteEngineOptions on the Encryption page, several types on Audit Trail and GDPR). Context7 knows BLite only as a crawl of the website (/websites/blitedb, reputation "Low"), with a description that says "memory-mapped files", a claim also found in the stale .agent/context.md (v1.11.0).

This epic is everything around the code that a team needs before it bets a product on v6. Each item is small and can be its own PR. Most can land in 5.3 already, so that v6 ships with them rather than waiting on them.

Done when

• docs/migrating-to-6.md covers every breaking change, and every v6 changelog entry that breaks something links to its section.
• A v5.2.x database file opened by v6 is checked by a test against the same contents, and the guide states what happens on first open.
• The changelog is written for consumers and is the source of the GitHub release notes; a release cannot be tagged with an empty or undated section.
• Every C# block in the README and in docs/ is compiled by a test, or carries a marker saying why it is not.
• SECURITY.md exists, private vulnerability reporting is enabled, and the release attaches an SBOM per package.
• Packages are published through NuGet Trusted Publishing, without a stored API key.
• BLite is indexed by Context7 from this repository, and the README links to it.

1. Migration guide and compatibility policy (before 6.0.0)

• docs/migrating-to-6.md. One section per change, each saying what now builds, runs or answers differently and what to write instead. It starts with what stays the same (target frameworks, package names), then "Back up first", then the changes in order of how likely they are to hit a user.
• File format upgrade path. State which engine versions open which files, whether v6 upgrades a v5 file in place on open or needs BLiteMigration/export–import, whether the upgrade is resumable after a crash, and that a v6 file cannot be opened by v5. The index key format change (Typed secondary index keys are not prefix-free: values containing bytes 0x00–0x03 are mis-bounded #212, DynamicCollection secondary index keys are not unique: deleting entries of a heavily duplicated value is quadratic #234) rebuilds indexes: say when, and what it costs on a large collection.
• Golden-file test. Databases written by v5.2.x (typed and dynamic, with indexes, encrypted, multi-file) checked in as fixtures; v6 opens each one and the store model compares the contents. This is the oracle for the migration path.
• Behaviour changes, not only API changes. WalSyncMode.Full as default and its commit cost (fix(wal): sync the WAL to disk before a commit is acknowledged #280), query results that change because an index now agrees with LINQ (Typed collections: == null and OrderBy(nullable).Take(n) served from an index return no null-keyed documents (indexes skip null keys, planner reads the null bucket) #247–A NaN with the sign bit clear sorts above +Infinity in an index on a double #257), BLQL semantics (BLQL filters and sorts cannot reach a nested field, though a dynamic index can be built on one #264–BLQL compares two Int64 values through double #268). Each gets a section, because none of them shows up as a compile error.
• What SemVer means here. One paragraph in CONTRIBUTING.md: a major for a public API removal, a file format change, a changed default, or a query that returns a different answer. A minor for additions. A patch for fixes that do not change a correct answer.
• API compatibility as a check. EnablePackageValidation with PackageValidationBaselineVersion set to the last 5.x release, so every v6 API break is listed in CompatibilitySuppressions.xml and therefore in the guide. After 6.0.0 the baseline moves to 6.0.0, and a minor that breaks the API fails the build.
• Support for 5.x after 6.0.0. State for how long 5.x gets security and data-loss fixes (for example six months), in SECURITY.md.

2. Changelog (can start in 5.3)

• Written for consumers. Every entry says what a user has to change, if anything. A breaking change gets its own paragraph naming the call that now answers differently, with a link to the migration guide. Sections per release: Breaking, Added, Changed, Fixed, Security.
• No empty or undated releases. A heading reads ## 6.0.0 — Unreleased until the release is prepared; the release workflow refuses a tag whose section is empty or still says Unreleased.
• Per-package changelogs (BLite, BLite.Core, BLite.Bson, BLite.SourceGenerators, BLite.Caching, BLite.Wasm) filtered from the root one, packed into each package.
• Release notes from the changelog. The GitHub release body is the changelog section, not the commit list.
• Keep versionize or not. Conventional commits can stay as input; the published text is curated. Maintainer's call.
• Fold the old release notes in. WHATS_NEW_4.3.md, README-5.0.0-preview.0.md and the v4/v5 banners at the top of the README move into the changelog or an archive folder.

3. Documentation (can start in 5.3)

• Docs live in this repository (docs/), versioned with the code and reviewed in the same PR as the change. BLite.Website renders them instead of keeping its own copy, so a PR that renames an API cannot leave the website behind.
• README as a landing page. It is 1,220 lines today. Keep: the pitch and the niches from Where BLite fits, and a reliability-first roadmap #287, "When not to use BLite", the stability matrix from Epic: reliability before features — durability, AOT, query correctness and oracle coverage #288, a quick start, and a table linking every docs page. The feature reference moves to docs/.
• Page set, mirroring the library sections that Epic: reliability before features — durability, AOT, query correctness and oracle coverage #288 gives an oracle:
  • Getting started (typed and schema-less, five minutes each)
  • Choosing BLite: how it compares, "Choose something else when", dated and versioned
  • One page per feature: LINQ, indexes, BLQL, vectors, geo, TimeSeries, CDC, KV/TTL, caching, transactions, sessions, multi-file
  • Platforms: Native AOT and trimming (absorbs AOT_LIMITATIONS.md), Unity IL2CPP, MAUI, Blazor WASM (absorbs WASM_SUPPORT.md)
  • Operations: WAL sync modes and what each guarantees, backup, VACUUM, single ↔ multi-file migration, multi-process mode, recovery
  • Security and compliance: encryption and key rotation, audit sink, GDPR primitives, DPIA checklist (exists in docs/), notes for integrators (section 6)
  • Testing (TESTING.md from Epic: reliability before features — durability, AOT, query correctness and oracle coverage #288)
  • Troubleshooting and FAQ
  • Specifications: RFC.md and C-BSON.md move to docs/spec/
• Every feature page states its guarantees and its stability label, the same label as the matrix.
• API reference generated from XML docs. GenerateDocumentationFile on every shipping project, with CS1591 as an error, so a public member without a doc comment does not build.
• Doc checks: relative links and anchors resolve; the README packed into each package uses absolute links only; every API a page names exists in the source.
• One voice. English throughout, including workflow comments, so contributors can follow the release pipeline.
• Three layers, each with one job, written down in CONTRIBUTING.md and checked by tests:
  • A package README (src/<Package>/README.md) is the reference for that package. It is what nuget.org shows, so it stands alone and links out with absolute URLs only. Today five packages pack the 1,220-line root README, whose relative links (RFC.md, C-BSON.md) are broken on nuget.org, and BLite.Caching packs no README at all.
  • A docs page (docs/<topic>.md, one topic each, named by a noun: vector-search.md, encryption.md, migrating-to-6.md) is a guide written around examples. The root README's "Documentation" table lists every page, and a test fails when a page is missing from it or the table links a page that does not exist.
  • Design and specification (docs/design/, docs/spec/) hold RFC.md, C-BSON.md, the multi-process WAL design and decision records. They are for contributors, are not compiled, but their links are checked.
  • The same code block is never in two places; a page links to the reference instead of repeating it.
• A plain, friendly voice for consumer docs, written down as a short style guide (and as an agent skill, so AI-assisted docs PRs follow it too):
  • Write to "you"; say what the reader gets first, then how it works; one idea per sentence, about 20 words at most; active voice
  • No hype and no filler: no "simply", "just", "easy", "seamless", "powerful", "blazing", "zero-cost", no exclamation marks or emoji in headings
  • Page shape: one or two sentences, then the smallest working example; headings are tasks or questions ("Encrypt an existing database"); edge cases last under "Good to know"
  • Facts stay exact: rewording never drops a condition, it moves it to "Good to know"
  • A glossary of BLite's own words (page, collection, C-BSON, WAL, checkpoint, sync mode) so each concept has one name
  • Before renaming a heading, search for links to its anchor, because exception messages and other pages point at it
• Moving from LiteDB — a guide, an API mapping and an import tool, as the maintainer suggested in Discussion #14. Tracked in Moving from LiteDB: a guide, an API mapping and an import tool #297.

4. Code samples (can start in 5.3)

• Compiled snippets. Every C# block in the README and in docs/ is a region in a samples test project (// sample: {page}/{name}), and a test fails when the block and the region differ. Outputs shown in comments are asserted. A block that cannot compile carries <!-- not compiled: reason -->.
• Runnable samples per niche under samples/, built in CI:
  • Console quick start (typed and dynamic)
  • Offline-first MAUI
  • Unity (IL2CPP), with the netstandard2.1 caveats
  • Blazor WASM (exists; update with BLite.Wasm: package lacks its JS files and offers no typed-context factory #293)
  • Local RAG: embeddings and vector search next to the documents
  • Encrypted database with [PersonalData], subject export and secure erase
  • Native AOT console app (the test(aot): Native AOT smoke test, a consumer under JIT and AOT with the publish log as oracle #277 smoke test, reframed as a sample)
• Consumer smoke test from the packed packages, outside the repository with its own NuGet cache, so a sample proves the published package and not a project reference.

5. Context7 and agent-facing docs (can land now)

• context7.json at the repository root, indexing README.md and docs/ and excluding tests, roadmap/ and the porting notes; claim the library so the repo entry replaces the website crawl.
• README badge and backlink to the Context7 entry, and a short "Using BLite with AI coding assistants" note with the library ID.
• AGENTS.md replacing .agent/. The current files describe v1.11.0, memory-mapped I/O and a PowerShell-only rule. The new file: build and test commands, the oracle suites and how to run each, invariants (no reflection at run time, AOT-safe, async-only CRUD), commit conventions and trailers, and the rule that a fix comes with a test that fails without it. A test checks that the commands it names exist.
• llms.txt (open): only if Context7 does not cover the need.

6. Governance and EU regulation (can land now)

• SECURITY.md (none today):
  • GitHub private vulnerability reporting, enabled in the repository settings
  • Acknowledgement and first assessment times stated as expectations, not an SLA
  • Coordinated disclosure with a 90-day ceiling; fix and GitHub advisory published together, reporter credited
  • Advisories go to the GitHub Advisory Database, so dotnet restore (NuGetAudit) warns every consumer
  • Supported versions table, with a horizon tied to the .NET 10 LTS end (November 2028)
  • In scope: silent data loss, acknowledged commits that are gone, encryption that fails open, secure erase that leaves bytes, BLQL injection or ReDoS, a corrupt or hostile database file that crashes the process instead of failing loudly. These are the guarantees that act as security controls.
  • Where BLite sits: in-process, with the application's permissions; the database file and BLQL strings are its inputs
  • What happens if the project stops being maintained
• CONTRIBUTING.md rewrite (it still says "Contributing to DocumentDb"):
  • The quality bar first: BLite's typical failure is silent (a commit that is gone after a crash, an index that answers differently than LINQ), so a fix comes with a test that fails when the fix is reverted (the oracle seed rule from test: oracle tests for the LINQ provider and the typed collection store #250)
  • One concern per PR, a changelog entry, docs in the same PR
  • Commit conventions and the Found-By: / Defect-Class: trailers
  • An "AI-assisted development" section: what is accepted and on what basis (behaviour and tests, not provenance), and who is accountable (the human who submits)
• PR template: test that fails without the fix, seed if it is an oracle, changelog entry, docs, migration note if it breaks anything.
• ROADMAP.md replacing the README's "Roadmap & Status" list, with each item marked Decided, Proposed or Open; roadmap/v5/ moves to an archive.
• Tidy the root: scripts (*.ps1, *.bat) to tools/, porting and branding notes to docs/.
• EU regulation: notes for integrators (docs page, plus one paragraph in SECURITY.md). As free, non-commercial open source, BLite itself is outside the Cyber Resilience Act and the Product Liability Directive, and the AI Act does not apply to a database library. Its users are another matter: Where BLite fits, and a reliability-first roadmap #287 names regulated EU software as a target niche, and a manufacturer who ships BLite in a commercial product must do due diligence on its components and report actively exploited vulnerabilities (CRA, applicable since 11 September 2026, fully from 11 December 2027). That manufacturer must also report a vulnerability it finds in a component to that component's maintainer. From 9 December 2026 it is liable for defective software, including missing security updates (PLD). What BLite can give them is what this epic lists anyway: a reporting channel, a support period, advisories that reach NuGetAudit, an SBOM, documented guarantees with tests behind them, and a changelog that names security fixes. No compliance artefact for a regime BLite is not in.

7. Release engineering and supply chain (before 6.0.0)

• Directory.Build.props shared by all shipping projects: package metadata, GenerateDocumentationFile, EnablePackageValidation, Source Link, symbol packages (snupkg), ContinuousIntegrationBuild on CI, TreatWarningsAsErrors with the NuGetAudit warnings exempted rather than suppressed. GeneratePackageOnBuild removed, so packing is an explicit, checked step.
• Central package management (Directory.Packages.props) and a pinned SDK (global.json).
• A CI workflow separate from publishing, on every PR, on ubuntu, windows and macos. File locking, fsync and the multi-process SHM differ by OS, which is where WAL commits are never flushed to disk: a power loss drops acknowledged commits and can leave documents pointing at freed pages #260 and the multi-process issues live. It runs the netstandard2.1 test project and the oracle suites agreed in Where BLite fits, and a reliability-first roadmap #287; the AOT smoke test (test(aot): Native AOT smoke test, a consumer under JIT and AOT with the publish log as oracle #277) and the browser harness (test: browser harness for BLite.Wasm (OPFS, IndexedDB, in-memory; trimmed and AOT) #295) run nightly.
• Release workflow in three jobs: verify (full suite, pack, smoke test, SBOM, no secrets), publish (NuGet Trusted Publishing through OIDC, replacing NUGET_API_KEY), release (GitHub release from the changelog, SBOMs attached). No job holds both id-token: write and contents: write. The tag must equal the packed version; a manual run is a dry run by default.
• A CycloneDX SBOM per package, attached to each GitHub release.
• Actions pinned to commit SHAs with the version in a comment, read-only default permissions, and a concurrency group per PR.
• Dependabot: actions weekly, test dependencies monthly; shipping dependency floors are a release decision and stay manual.
• Open, beyond the above: build provenance attestations, OpenSSF Scorecard, CodeQL.

8. Clean-up: what the repository should let go (can land now)

The structural causes behind the defects below (two write paths, two collection implementations, nine key encoders, no conflict detection) and the v5 → v6 migration are proposed as decision records in #308.

An audit of upstream/main at 0450b97 found files that are dead, misplaced, or wrong in a way a user or an AI assistant would act on. Every item below was checked against src/.

Wrong today, fix first (these mislead users and agents):

• The README documents APIs that do not exist. No match in src/ for RotateEncryptionKeyAsync, KeyRotationOptions, MigrateToEncryptedAsync/MigrateToPlaintextAsync, HasSecureErase(true); synchronous forms that v4 removed or never had: FindById, Insert, engine.Commit(), BLiteMigration.ToMultiFile(/ToSingleFile(, CreateSpatialIndex( (the source has the *Async forms); VacuumAsync() on a context. The roadmap list says key rotation has shipped. Because every package packs this README, nuget.org shows the same samples. The compiled samples of section 4 stop this from coming back. → PR docs(readme): show only APIs that exist in the source #298 (also: BsonDocument has no GetString/GetDouble/Id, BsonSpanReader no TryReadString).
• Three answers to "is a deleted document erased?" README: HasSecureErase(true) zeros the slot. GdprStrictValidator at run time: "SecureEraseOnDelete is not yet available as an engine-level setting", pointing to MISSING_FEATURES.md §3. docs/DPIA_CHECKLIST.md: call VacuumAsync after deletion. For a GDPR feature this needs one answer, stated once, with the GDPR oracle of Epic: reliability before features — durability, AOT, query correctness and oracle coverage #288 behind it. What the code does: every delete zero-fills the document's bytes (overflow pages included), and the database file gets them at the next checkpoint. README → PR docs(readme): show only APIs that exist in the source #298; the runtime warning → GdprMode.Strict warns that deleted documents are not zeroed, but every delete zero-fills them #299; the DPIA checklist still open.
• A context whose class name does not end in Context is silently skipped by the generator: no generated code, no diagnostic, every collection null → A DocumentDbContext whose class name does not end in "Context" gets no generated code and no diagnostic; its collections stay null #300. The README's own samples used such a name until docs(readme): show only APIs that exist in the source #298.
• The schema-less API cannot read a typed collection with a document larger than one page (about 16 KB): FindAllAsync throws "Skipping type 69", so BLiteMigration, Studio and BLQL fail on such a database, and DynamicCollection refuses to write one; the limit is documented nowhere → The schema-less API cannot read a typed collection that holds a document larger than one page: FindAllAsync and BLiteMigration throw "Skipping type 69" #301. The stability matrix should say what the schema-less API supports until it is fixed.
• The README promises snapshot isolation, but two concurrent transactions both commit and one is silently lost (typed, engine and two BLiteSessions alike) → Two concurrent transactions both commit, and one of them is silently lost: no write-write conflict detection #304. Until a fix lands, the README must not claim snapshot isolation or concurrent sessions.
• An engine and a session hold separate instances of one collection: an index created through one misses the other's writes, and a session commit can erase the index definition → An engine and a session hold separate DynamicCollection instances: an index created through one misses the other's writes, and a session commit can erase the index definition #305.
• BsonValue equality is wrong for negative Int64 and pre-1970 dates (FromInt64(-1) != FromInt64(-1)), which breaks HashSet, Dictionary, Distinct and GroupBy over document values → BsonValue equality is wrong for negative Int64 and pre-1970 dates: FromInt64(-1) != FromInt64(-1), and FromInt64(0) == FromInt64(long.MinValue) #306.
• BLiteSession.Rollback() does not await the rollback, and the README's session sample calls it in its catch block → BLiteSession.Rollback() does not await the rollback: it returns while the transaction is still active, and failures go unobserved #307.
• RFC.md, linked as the "full architectural specification", says multi-process is "❌ Not Supported", page checksums are "CRC32" (every writer sets the checksum to 0), there is no query language (BLQL exists), and encryption is planned (it shipped in 5.0). It is "Version 0.2.0".
• C-BSON.md does not describe the 0xCB offset-table header that every generated root document has carried since April 2026, so a port or a tool written from the spec misreads real documents.
• .agent/context.md and .agent/rules.md describe v1.11.0: db.Users.Insert(...), tx.Commit(), a website/ folder, "memory-mapped files". rules.md tells agents to trust context.md and to update it every session, which has not happened since February. Replaced by AGENTS.md (section 5).
• .github/workflows/studio-release.yml gives the Studio package's homepage as https://github.com/stephaneclaudet/BLite, which is not this repository.

Delete (dead, unreferenced or superseded):

• One-shot or broken workflows: create-v5-issues.yml with .github/v5-issues.json (a second run files 18 duplicate issues), deploy-website.yml (builds website/, which moved to BLite.Website in March; also drop !website/dist from .gitignore)
• Old release notes and notes on things that do not exist: README-5.0.0-preview.0.md ("Estimated GA: 30 May 2026"), PORTING_DART.md and PORTING_KOTLIN.md (they list [BCollection] and [BIndex], which BLite does not have)
• Root scripts nobody references: analyze-core-mutations.ps1 (empty), check-disk.ps1 (prints free space on C:), clean-test-temp.ps1, build-studio-msi.bat (duplicates the Studio workflow, defaults to version 1.9.0)
• Finished TODO files: src/BLite.Core/TODO.md and src/BLite.SourceGenerators/TODO.md (a byte-order mark only), src/BLite.Core/Indexing/HNSW-TODO.md (all ten items are implemented)
• Projects that cannot build or duplicate a test: src/BLite.Demo (no project file), tests/BLite.Debug, tests/BLite.CheckpointTest (DocumentDb.CheckpointTest.csproj); fold anything still wanted into the benchmarks
• Committed output: two .trx files under tests/BLite.Tests/TestResults/ (they carry a machine and user name), two UTF-16 logs in tests/BLite.Benchmark/, the stale tests/BLite.Benchmark/RUNNING.md, the Avalonia template logo in Studio's assets (the largest file in the tree)
• Finished v5 plans in roadmap/v5/ (audit, encryption, encryption fix, missing features, GDPR): everything they plan has shipped or was dropped. Move the two open items of ENCRYPTION_FIX_PLAN.md to issues, and re-point the links from docs/DPIA_CHECKLIST.md, GdprStrictValidator.cs and GdprStrictTests.cs first

Move (useful, wrong place):

• roadmap/v5/MULTI_PROCESS_WAL.md → docs/design/multi-process-wal.md; update the seven code comments that link it, and its option name (EnableMultiProcessAccess → AllowMultiProcessAccess)
• AOT_LIMITATIONS.md, WASM_SUPPORT.md, BENCHMARKS.md → docs/ pages (section 3); WASM_SUPPORT.md names pages and routes the sample no longer has
• WHATS_NEW_4.3.md → docs/ (it is the only documentation of generated filters and BLiteEnableInterceptors)
• RFC.md, C-BSON.md → docs/spec/, after the corrections above; BRANDING.md → BLite.Website
• tests/BLite.ConsoleSample → samples/ (it is a feature tour, not a test); tests/BLite.StressMonitor → tools/
• Mutation testing (run-mutation-tests.bat, three stryker-config.json, dotnet-tools.json) → tools/mutation/ and .config/dotnet-tools.json, run from a cross-platform script or a .NET tool, with each run's result kept as a dated report

Tidy:

• BLite.slnx: the solution folder is named "Elementi di soluzione", it lists a Directory.Build.props that does not exist, and tools/BLite.RawDump is not in it (add it or delete it)
• One copyright holder: LICENSE.txt says "2025 mrdevrobot", Studio's copy says "2026 BLite Project"
• Studio's AssemblyVersion (5.0.2.0) is not bumped with Version (5.2.3)
• The bug report template offers BLite, Core and Bson only (and calls the meta-package "client SDK"); add SourceGenerators, Caching, Wasm and Studio, and the auto-labelling in issue-precheck.yml with them
• English for the Italian left in workflows (about 50 lines across nuget-publish.yml and bump-version.yml), two test comments and icon.svg
• The old name "DocumentDb" in CONTRIBUTING.md, .agent/rules.md, BLite.slnx and the checkpoint test (DocumentDbContext is the public API and stays)
• .gitignore: add TestResults/, *.trx, StrykerOutput/, .idea/

History note: website/dist is 16.6 MB of the 62.5 MB of blob history. Only a history rewrite reclaims it, which is not worth breaking every fork for; listed so nobody looks for it again.

9. GitHub and NuGet presence (can land now)

Repository (settings only the maintainer can change):

• Description that carries the pitch from Where BLite fits, and a reliability-first roadmap #287 instead of "Embedded Document Database", for example: "Managed, AOT-ready embedded document database for .NET: LINQ, vectors, geo and time series in one file, with encryption and GDPR built in."
• Homepage set to the docs site (the field is empty).
• Topics (there are none), for example: database, embedded-database, document-database, nosql, bson, dotnet, csharp, linq, source-generators, native-aot, blazor-wasm, maui, unity, vector-search, hnsw, geospatial, time-series, encryption, gdpr, offline-first, litedb-alternative.
• Social preview image from icon.svg.
• Branch protection and rulesets: required checks with names that never change (a renamed job leaves a required check that never reports and blocks every PR), an immutable v* tag ruleset, and the nuget environment accepting deployments from v* tags only.
• Stacked PRs get CI too. The workflow runs on PRs into main only, so a PR based on another PR's branch gets no checks. Either run CI on every PR, or keep stacks short and say so in CONTRIBUTING.md.

NuGet packages (all six, plus Studio):

• A README per package (section 3), packed from src/<Package>/README.md, with a test that fails on a relative link.
• Descriptions that say what the package is for and which package to install, instead of the same "High-Performance BSON Database Engine" on four of them. Today a user cannot tell from nuget.org whether to install BLite or BLite.Core.
• Tags that match the positioning and drop what is stale: remove xamarin (out of support since May 2024) and net10;netstandard21 (nuget.org shows the frameworks), reconsider zero-allocation (Epic: reliability before features — durability, AOT, query correctness and oracle coverage #288); add document-database, linq, source-generator, aot, trimming, vector-search, geospatial, encryption, gdpr, offline-first, blazor, litedb. A test checks that every package has a description, tags, a README and the icon.
• Metadata shared in Directory.Build.props: PackageProjectUrl (empty on all six), RepositoryUrl with RepositoryType and the commit through Source Link, Copyright, Authors as the maintainer's nuget.org name, PackageReleaseNotes linking the version's changelog section.
• BLite.Caching gets the icon and README the others have.
• Reserve the BLite. ID prefix on nuget.org, so the packages show as verified and nobody else can publish BLite.Something. None of the eleven EntglDb packages is verified today.

BLite Studio:

• Signed builds that open on Windows, macOS and Linux, on Avalonia 12, built and smoke-tested on every PR → BLite Studio for v6: Avalonia 12, signed builds on all three desktop platforms, built and tested on every PR #309. Studio ships for all three platforms today, but the macOS build is ad-hoc signed and Gatekeeper rejects it, and nothing builds Studio outside a release tag.

10. Engineering habits worth adopting (second iteration)

These are smaller rules that hold the quality once the work above is done. Each one has stopped a real defect elsewhere.

• .gitattributes: * text=auto eol=lf, and *.db, WAL and BSON fixtures marked binary. A line-ending rewrite silently corrupts a binary test database, and the golden files of section 1 are exactly that. Plus an .editorconfig so a first save does not reformat the file.
• Exception messages that help: every deliberate refusal (corrupt file, lock timeout, schema mismatch, AOT limitation, invalid BLQL) says what to do instead and links to its "Why does this throw?" section in the docs; a test keeps the links valid.
• No exception message or log line quotes document content. A document can hold personal data, and BLite markets GDPR support. Quote a field name and a length, never the value. A test feeds a marked value through every error path.
• Culture sweeps: BLQL parsing, number and date text, and string key ordering checked under several cultures (de-DE, tr-TR, ar-SA, invariant), and DOTNET_CLI_UI_LANGUAGE=en wherever a tool parses dotnet output.
• Experimental features marked in code, not only in the stability matrix: [Experimental("BLITE0001")] on multi-process mode and the WASM backends until their issues close, so a user opts in knowingly and the compiler says so.
• A deprecation policy: [Obsolete(DiagnosticId = "BLITE…", UrlFormat = "…")] in a minor, removed in the next major; diagnostic IDs of the source generator and of obsoletions are never renumbered; each intended API break has its own entry in CompatibilitySuppressions.xml.
• Benchmarks are not a gate, allocation tests are. BENCHMARKS.md is a dated table with hardware and sync mode, re-run before a release. What must hold (the read-path allocation claim in the README) is a test that measures allocations.
• Repository tooling in C# (dotnet run file-based apps or a tools project) rather than .ps1 and .bat, so it runs on every OS the CI uses; one-off investigations go in spikes/ with a README that states the question, the answer and the evidence.
• CI never depends on an AI being available: no test or workflow reads agent state, and agent files (AGENTS.md, skills) are optional helpers, not part of the build.
• Test conventions: test names are sentences; a test that discovers its cases asserts a minimum count, so an empty discovery fails; slow or environment-bound suites report inconclusive locally but fail when CI=true.
• Commit conventions: keep conventional commits (versionize reads them) plus the Found-By: / Defect-Class: trailers from Where BLite fits, and a reliability-first roadmap #287, with a test that reads git log; merge commits for multi-commit branches, so the history of a fix stays readable.

Order

1. The "wrong today" items of section 8, section 9's repository settings, section 5 and SECURITY.md: small and independent; they can land in 5.3.
2. Directory.Build.props, the CI workflow and package validation against 5.x: they make the rest checkable.
3. The rest of section 8, then docs into the repository with the three layers and the voice guide, compiled samples, the changelog format, per-package READMEs.
4. The migration guide and the golden-file test, written alongside the format change (Typed secondary index keys are not prefix-free: values containing bytes 0x00–0x03 are mis-bounded #212, DynamicCollection secondary index keys are not unique: deleting entries of a heavily duplicated value is quadratic #234), not after it.
5. The release workflow, used first for 6.0.0-preview.1.

I'm happy to do any of these as separate PRs, in this order or in the one you prefer.