AGENTS

Scrinium Wiki

This repository is the GitHub wiki for 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 https://github.com/Etherna/scrinium/wiki 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 <TModelBase> 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/<folder>/<file>.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 https://www.diagrams.net/) for rich graphics Mermaid can't express. The one theme-aware image, the brand logo on Home, is a <picture> element instead: the dark variant in a <source media="(prefers-color-scheme: dark)"> and the light one as the <img> 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-<id>) 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.