docs: correct the import advice, which was true in spirit and false as written
Home.md said "You cannot hand-pick a few projects" and pointed every reader at
the 163-import compile gate. The Sandbox reaches ten layers -- stores, SQL,
migrations, caching, workflow, jobs, health, REST, GraphQL, security -- with 38,
so the absolute form is measurably false, and following it makes every consumer
carry nearly the whole framework.
What was actually true is the direction of travel: start from a list that
compiles and delete, rather than adding one project at a time and discovering
the graph one compiler error at a time. Both pages now say that, and bracket the
range with the two real references (38 and 163) so a reader can pick the end
they would rather work from.
birko
committed
Sep 18, 2026
correct six API errors the snippet compiler found
Building every code block turned up mistakes that reading could not:
- ISchemaBuilder has CreateCollection and CreateIndex - there is no AlterCollection,
so the migration example was written against an API that does not exist
- IMigration requires six members (Version, Name, Description, CreatedAt, Up, Down),
not the two the example showed
- IndexedField takes a required index name
- set-membership filters need List<T>, not an array: on .NET 9+ array.Contains binds
to MemoryExtensions.Contains(ReadOnlySpan<T>, T) and a ref struct cannot appear in
an expression tree, so the filter does not compile
- AbstractModel.Guid is nullable, so the list element type is Guid? too
- the Security page used one name for both the JWT provider and the secret provider
Adds the verify:context and verify:skip markers the CI job reads. Both are HTML
comments, so neither renders. Context exists because most blocks are fragments by
design - they use store and product because the prose just introduced them, and a
guide should not have to be written for the compiler. Four blocks are skipped, each
with a stated reason: they reference types the reader writes.
birko
committed
Sep 18, 2026
Home + Getting Started: a usage guide grounded in verified examples
Every snippet was compiled and run against the current framework before being
written down, rather than copied from existing docs - several of which are stale
and are named as such on the Getting Started page.
The headline finding is that you cannot hand-pick .projitems imports: ten rounds
of adding one project at a time still had not closed, because the graph pulls
models, view-models, serialization and rules in behind the SQL stores. The guide
therefore tells people to copy the Sandbox aggregator's 163-import list, which is
proven to compile, rather than building one up.
birko
committed
Sep 18, 2026