# Scrinium Wiki This repository is the **GitHub wiki** for [Scrinium](https://github.com/Etherna/scrinium) — the Object-Documental Mapper for MongoDB on .NET. It is the user-facing documentation: what Scrinium is, how to install and configure it, and how to use every feature with concrete, working examples. It contains **only Markdown content**, no source code. Published at from the `master` branch of `https://github.com/Etherna/scrinium.wiki.git`, which holds released documentation only: the work happens on the branches mirroring the code repository (see "Branches mirror the code repository"). ## Source of truth The **code is the source of truth**, this wiki follows it. Never document an API from memory or from an older wiki page — every statement, signature, option and code sample must be verified against the actual Scrinium source before writing it. Every statement must also be **unambiguous**: written so it admits exactly one reading, with no vague qualifiers or unclear referents — if a sentence could be read two ways, rewrite it as the single precise claim the code supports. ## Verification rules Concrete checks for every statement, each added after a real audit caught its failure mode. Apply them when writing a page and again when the code a page depends on changes: 1. **Trace every behavior claim to its code.** For "X happens when Y", read the implementing code — the call site, the throw site, the actual caller — before writing. Verify the *direction* (who writes vs who reads), the *trigger* (what really enqueues/builds/evicts, not what plausibly would), and the *actor* (which component does it). A claim you cannot point to a line for does not get published. 2. **Compile-check every snippet** against the current `../scrinium` build and the Etherna driver version it references. Frequent traps: generic-type inference (write explicit type arguments when the API can't infer them), extension methods that don't exist on the shown type, incomplete `using` blocks (if a snippet shows usings, show *all* it needs), types used but never defined in the snippet or the sample, missing service registrations in startup samples. 3. **State the boundary of every guarantee.** Locks, caches, uniqueness and any "never/always/only" must name their scope: per process, per DI scope, per db context, per schema. An unqualified guarantee is assumed wrong until the code shows it is truly global. 4. **Use only API names that exist, spelled exactly.** Grep the current source for every type and member name cited; renamed members are the most common stale error. When the code renames an API, grep the whole wiki for the old name in the same work line. 5. **Attribute features to their real library.** If a capability lives in a sibling or ecosystem repo that `../scrinium` does not reference, it does not appear here — even when the two are commonly used together. 6. **No purpose claims without code evidence.** Document what an API *does* (members, observable behavior); state what it is *for* only when code, samples or tests show that use. 7. **Grep invented example names against the consumer-service repos** before publishing; any type/member that matches a real service domain gets renamed to the neutral set. 8. **Keep pages consistent with each other.** Before changing or adding a claim, grep the other pages for the same topic and align every occurrence in the same change — two pages disagreeing means at least one is wrong. 9. **Tripwire words — rewrite on sight**: "no longer", "previously", "used to", version comparisons outside the Since/Changed-in convention; "not yet", "coming", "will be", "proposal"; "generally", "usually", "typically", "can be" where the code is deterministic; "raw" for objects the library actually wraps or guards. - The Scrinium repo is checked out next to this one: `../scrinium`. Read from it to verify anything you document, with both checkouts on the same work line (the wiki branch mirroring the code branch). - The wiki is kept in step with the code by the code changes themselves: every substantial change to the public API, configuration, features or architecture updates the affected wiki pages in the same work line (the `scrinium` repo's `AGENTS.md` mandates this). ## Documented version & versioning The wiki documents **one** line of Scrinium at a time — the **current development line** — and tracks its release status on the [[Versions]] page. Today that line is **`0.25`**, released on 2026-09-03: the first supported line, which the current `dev` branch continues (scoped `DbContext` over a singleton `DbContextEngine`, `MapRegistry`, member-level saves, per-scope identity map, source repositories; no `DbCache`). Do **not** document pre-0.25 APIs (`DbCache`, `SchemaRegister.AddModelMapsSchema`, `ICollectionRepository`, the `` generic on `AddScriniumWithHangfire`, the standalone `ExecutionContext` package). Version status lives in exactly two places — the banner near the top of `Home` and the `Versions` table — not on every page. Keep the two in sync. Versions are always named as `major.minor` lines (`0.25`, `1.0`) — in page prose, inline flags, `Versions` rows, the `Home` banner and wiki tags alike — never as a full `x.y.z`. A hotfix release (`x.y.z` with `z > 0`) belongs to its line and fixes behavior the line already declares by design, so the pages state the fixed behavior as plain fact: no **Since**/**Changed in** mark, no row, no tag, no mention of the hotfix version. Its edits live on the `hotfix/x.y.z` wiki branch and publish with the release merge into `master`. **When a version ships or a new line opens:** - On **release** of a line, merge its wiki branch into `master` **and**, as a second merge of the same branch, into `dev` — never propagate `master` into `dev`: with the two in sync it lands the same, but it isn't true in general. Then flip that version's row on `Versions` from `dev` to released and drop the `dev` mark from the `Home` banner, and tag the wiki repo (e.g. `v0.25`) so the released page set stays recoverable. A hotfix release merges its `hotfix/x.y.z` branch the same way, touching neither `Versions`, `Home` nor tags. Once both merges are pushed, delete the line branch, locally and on origin. - When the **next line** opens (`1.0`, with new principles), it becomes the new `dev` entry at the top of `Versions` and the `Home` banner; the last released line stays listed. Its pages live on the wiki `dev` branch until it releases. Document the new behavior in place and flag what differs **inline** on the affected pages — **Since `1.0`** for new behavior, **Changed in `1.0`** / **Until `0.25`** where it changed — so one page set serves both lines. Add the "upgrading" guide at that point. ## Branches mirror the code repository GitHub publishes the wiki from `master`, so `master` holds **released** documentation only: the page set of the last released version. Every documentation change is made on the wiki branch mirroring the code branch of its work line, with the same name: `dev` for the `dev` branch of `../scrinium`, `hotfix/x.y.z` for a hotfix line, `release/x.y.z` for a release line. Create the branch from `master` (from `dev` for a release line) when the code line opens, check it out before editing, commit and push there, and merge it into `master` only when the code line releases; merge the same branch into `dev` as a second, separate merge, and delete it afterwards on both sides. Documentation content never lands on `master` directly: it would publish behavior that isn't released. `AGENTS.md` and `CLAUDE.md` are process files, not documentation content: a convention change lands on `master` and merges forward into the open line branches right away, so every branch reads the same conventions. ## How a GitHub wiki works - Each `.md` file at the repo root is one page. The filename is the page identity: hyphens render as spaces (`First-steps.md` → page "First steps"). Use **kebab-case filenames**, **Sentence-case titles**. - Internal links use `[[Page title]]` for a full-title link, and standard Markdown `[custom text](Page-title-slug)` (slug = filename without `.md`, e.g. `DbContext-and-engine`) when the link text must differ. **Avoid the piped `[[a|b]]` form** — its argument order is ambiguous across wiki renderers. A link whose target page does not exist yet renders but 404s — only link to pages that exist, or that this change creates. - `Home.md` is the landing page. `_Sidebar.md` (navigation, shown on every page) and `_Footer.md` are special reserved pages — keep the sidebar in sync with the pages that actually exist. - Images live under `img/` and are embedded with `[[img//.png]]`. For schematic diagrams prefer inline **Mermaid** fenced blocks (```` ```mermaid ````), which GitHub renders natively and keep the diagram in the page source; reserve exported `img/` assets (authored with ) for rich graphics Mermaid can't express. The one theme-aware image, the brand logo on `Home`, is a `` element instead: the dark variant in a `` and the light one as the `` fallback, both addressed through the raw wiki URL (`https://raw.githubusercontent.com/wiki/Etherna/scrinium/img/...`), since the wiki link syntax carries no theme. The logo files under `img/brand/` are exports of the brand lockup, 400 px wide and shown at 200 px: regenerate them from the brand source, never edit them. - No page front-matter, no folders for content pages (keep the tree flat); GitHub renders standard GitHub-Flavored Markdown. ## Structure & navigation Pages are grouped into these sidebar sections (a page belongs to exactly one): 1. **Getting started** — Home, Packages and feeds, First steps, Startup and configuration 2. **Core concepts** — Architecture overview, Domain models, DbContext and engine, Repositories 3. **Working with data** — CRUD operations, Querying, Change tracking and saving, Transactions 4. **Serialization & mapping** — Model mapping, Versioned schemas, References and denormalization, Custom serializers 5. **Operations & maintenance** — Migrations, Database seeding, Background tasks, Admin dashboard, Indexes 6. **Advanced & reference** — Execution contexts, Exclusive access, Db context lock, Resource locks, Read-only access, Best practices and pitfalls, Exceptions reference When adding a page, place it in the right section, add it to `_Sidebar.md`, and cross-link it from related pages. Prefer one well-scoped page over a sprawling one; link liberally with `[[...]]`. ## Writing style - **Audience**: .NET developers using Scrinium in an ASP.NET Core app. Assume C# and basic MongoDB knowledge; do not re-explain the MongoDB C# driver — link to its docs for driver-level detail. - **Tone**: schematic and modern. Lead each page with a one-sentence statement of what it covers. Prefer short sections, tables for options/enums, fenced ` ```csharp ` blocks, and callouts (`> **Note**`, `> **Warning**`) for gotchas. Cut prose that doesn't help the reader act. - **Dryness is part of correctness.** The register stays formal, but every page must stay immediately usable: state each fact once — the page that owns a concept explains it, every other page links it with `[[...]]` instead of re-explaining; don't restate in prose what a table or snippet already shows; prefer the single precise sentence over the hedged paragraph. When editing a page for any reason, also trim what doesn't help the reader act: verbosity is a defect to fix on sight, like a stale claim. - **Examples must compile** against the documented version. Prefer real, minimal snippets grounded in `samples/AspNetCoreSample` or the integration tests. Omit the LGPL license header from snippets (it's boilerplate), but keep code otherwise faithful. - **Never name or reference the Etherna consumer services** (index, sso, gateway, credit, beehive) or their types in published pages. You may draw inspiration from how they use Scrinium (the sibling service repos) for real-world patterns, but present them with neutral example types (the running `Cat`/`Cats` domain, or plain `User`/`Order`/`Team`) — *inspired* by them, never *attributed* to them. This does not touch the library's own org/driver: `Etherna.MongoDB.*`, `Etherna.Scrinium.*` and `github.com/Etherna/scrinium` are correct and stay. - **Namespaces**: Scrinium uses the Etherna MongoDB driver fork — types are `Etherna.MongoDB.*` and `Etherna.Scrinium.*`. Never show `MongoDB.*` (official driver) namespaces. - American English. Second person ("you configure…"). Keep terminology consistent with the code (`DbContext`, `DbContextEngine`, `Repository`, `MapRegistry`, `IModelMapsCollector`, schema id…). ## Maintenance workflow - One logical change per commit; commit messages read as the team's own work. **Never reference AI agents or assistants** in commits or content — no agent names, no "generated/assisted by" notes, no `Co-Authored-By` agent trailers. - Keep `_Sidebar.md` and cross-links consistent when adding, renaming or removing pages. Renaming a file changes its URL — update every `[[...]]` and `[...](slug)` reference to it. - Do not commit `.idea/` or `.vs/` (git-ignored). ## Document only what exists — no todos, no issue references The wiki documents **only behavior that already exists in the code** — somewhere in `../scrinium`, even if not yet released — never planned, "todo" or future work. Write current behavior in the present tense as plain fact: a genuine limitation is documented as *how it works today*, with the workaround the code already supports, not as something "not yet" done, "coming", or tied to a future change. Do **not** cite specific Jira issues (`SCR-`) in published pages to explain a feature or limitation, and don't frame behavior as pending work — document the observable behavior instead. (Issue keys belong in commit messages and code, not in page prose.) A plain link to the issue tracker as a **resource** — in the `Home` resources list or the footer — is fine; it's a pointer, not a todo. This rule governs the published pages, not this `AGENTS.md`.