Improve discoverability: why paragraph, ecosystem links, and package tags

Documentation/goals.md

@@ -0,0 +1,30 @@
+---
+title: Adapter goals
+description: The bounded Marten and Wolverine semantics the adapter recovers, and the evidence and diagnostic boundaries it enforces.
+---
+
+The adapter recovers bounded Marten and Wolverine semantics from authorized source and reports explicit diagnostics whenever source behavior cannot be represented faithfully. This page lists the current goals in full; the [overview](index.md) summarizes the adapter and its boundaries.
+
+## Goals
+
+- Marten-only event stores, documents, aggregates, projections, and queries.
+- Generic and instance-based Marten projection registrations, with exact authored projection name/version evidence and explicit diagnostics for unsupported async/live lifecycle semantics.
+- Async daemon mode and first-class subscription registration/configuration evidence without inventing state views, automations, translations, events, messages, or document consequences from arbitrary processing code.
+- Marten document identities from exact configuration, identity attributes, and conventions, without guessing unresolved expressions.
+- Authored Marten event/document tenancy declarations, attributes, and global policies retained as located `MARTEN0013` diagnostic evidence without inferring effective state, runtime tenant resolution, or database topology.
+- Authored Marten event aliases, schema-version helpers, naming style, and current upcast registrations retained as `MARTEN0011`/`MARTEN0012` diagnostic evidence without renaming or originating events or inferring upcast behavior.
+- Marten compiled-query execution linked to proven Wolverine HTTP query entry points, including public plan parameters; unresolved nested executable flow reports `MARTEN0006` instead of guessing.
+- Marten + Wolverine HTTP and message handlers, including signature-stable overloaded handler identities and batched `T[]` message delivery.
+- Returned `IStorageAction<T>` / `UnitOfWork<T>` persistence, exact per-slot storage-factory refinement, and `[Entity]` / `[FirstOrDefault]` / `[Queryable]` bound reads.
+- Presence diagnostics for Wolverine/Marten convention-alteration hooks, per-chain `Configure(HandlerChain)`, and Marten session listeners without interpreting policy or listener bodies.
+- Compound `Load*`, `Before*`, `After*`, `PostProcess*`, `Finally*`, and after-commit stages, with exact outgoing-message consequences retained on the owning entry point and explicit `WOLVERINE0020` loss.
+- Literal projection `PublishMessage(new TMessage(...))` side effects retained as Message/`Publishes` evidence, with `MARTEN0015` for unresolved payload flow.
+- Event wire configuration (`UseBinarySerializer<T>`, append mode, stream identity) and `RegisterValueType` concept nomination retained without fabricating event or concept representations.
+- Vogen concepts, primitive representations, authored validation hooks, nullable usages, and explicit loss diagnostics through the separately composed `Cratis.Screenplay.Generation.DotNet.Vogen` adapter.
+- Current store-agnostic Wolverine event-sourcing APIs and legacy Marten-specific APIs.
+- Target-aware exact current and legacy `IEventStream<T>` appends across multiple handler parameters, including commandless HTTP and metadata-only loaded streams, with per-binding identities and explicit diagnostics instead of first-stream guesses.
+- Bounded current and legacy Wolverine DCB evidence from authored `[DcbModel]` / `[BoundaryModel]` parameters, direct `EventTagQuery` fluent chains, exact boundary appends, and safe declarative returns, with `WOLVERINE0014`/`WOLVERINE0015` instead of invented stream topology.
+- Bounded authored Wolverine saga discovery for public concrete closed `Wolverine.Saga` state, grouped by message with Wolverine-compatible `SagaChain` admission. It preserves admitted role spellings and `Async` twins, constructor/returned-state creation constraints, collision-safe handler identities, exact correlation precedence (including inherited public members), cascades, timeouts, direct bus calls, and exact `MarkCompleted()` evidence. Saga state is excluded at every final HTTP query, message, and event admission boundary. `WOLVERINE0016` is a report-only realization/provenance diagnostic: Wolverine-managed lifecycle is intentionally not lowered because authored source does not safely establish a portable domain workflow. Screenplay uses ordinary Event Modeling building blocks; this is not a language-gap request, and generated `.play` bytes remain unchanged. `WOLVERINE0017` reports runtime-resolved correlation, while `WOLVERINE0018` reports rejected lifecycle shapes without inventing persistence or transport topology.
+- Markerless event/message discovery from actual framework usage.
+- Deterministic output without starting the application or connecting to PostgreSQL.
+- Explicit diagnostics whenever source behavior cannot be represented faithfully.

Documentation/index.md

@@ -5,7 +5,7 @@ description: Understand the optional Marten and Wolverine source adapter and its
 
 Screenplay.CritterStack is an optional, pre-release compatibility adapter. Given an authorized .NET source context, it identifies bounded Marten and Wolverine semantics and contributes neutral facts, evidence, and diagnostics to Screenplay.Generation. The result is a reviewable Screenplay candidate; it is not an automatic migration or a claim of behavioral equivalence.
 
-The adapter library does not start the analyzed application or connect to its database. The host still owns workspace loading, source authorization, project and target-framework selection, and the trust boundary around MSBuild evaluation.
+The adapter library does not start the analyzed application or connect to its database. The host still owns workspace loading, source authorization, project and target-framework selection, and the trust boundary around MSBuild evaluation. The complete list of bounded semantics the adapter recovers lives in [Adapter goals](goals.md).
 
 ## Extend the adapter
 

Documentation/toc.yml

@@ -1,4 +1,6 @@
 - name: Overview
   href: index.md
+- name: Adapter goals
+  href: goals.md
 - name: Guides
   href: guides/toc.yml

README.md

@@ -6,29 +6,13 @@ Generate compiler-checked, reviewable [Cratis Screenplay](https://github.com/Cra
 
 This is an independent, optional pre-release Cratis compatibility project. It is not affiliated with or endorsed by JasperFx. Marten, Wolverine, JasperFx, and Critter Stack names belong to their respective owners. Generated models require human review wherever diagnostics report loss or ambiguity. The package is not an automatic migration authority, production runtime, compatibility promise, or support commitment.
 
+## Why
+
+If you have an existing event-sourced Marten + Wolverine codebase, Screenplay.CritterStack generates a reviewable, compiler-verified Screenplay model from that source — an optional, independent on-ramp to the Cratis model-first stack. The events, commands, projections, and handlers your code already expresses become a [Screenplay](https://github.com/Cratis/Screenplay) model you can inspect and evolve with [Stage](https://github.com/Cratis/Stage), [Chronicle](https://github.com/Cratis/Chronicle), and [Arc](https://github.com/Cratis/Arc). Wherever source semantics cannot be represented faithfully, explicit diagnostics mark the spot for human review instead of guessing.
+
 ## Goals
 
-- Marten-only event stores, documents, aggregates, projections, and queries.
-- Generic and instance-based Marten projection registrations, with exact authored projection name/version evidence and explicit diagnostics for unsupported async/live lifecycle semantics.
-- Async daemon mode and first-class subscription registration/configuration evidence without inventing state views, automations, translations, events, messages, or document consequences from arbitrary processing code.
-- Marten document identities from exact configuration, identity attributes, and conventions, without guessing unresolved expressions.
-- Authored Marten event/document tenancy declarations, attributes, and global policies retained as located `MARTEN0013` diagnostic evidence without inferring effective state, runtime tenant resolution, or database topology.
-- Authored Marten event aliases, schema-version helpers, naming style, and current upcast registrations retained as `MARTEN0011`/`MARTEN0012` diagnostic evidence without renaming or originating events or inferring upcast behavior.
-- Marten compiled-query execution linked to proven Wolverine HTTP query entry points, including public plan parameters; unresolved nested executable flow reports `MARTEN0006` instead of guessing.
-- Marten + Wolverine HTTP and message handlers, including signature-stable overloaded handler identities and batched `T[]` message delivery.
-- Returned `IStorageAction<T>` / `UnitOfWork<T>` persistence, exact per-slot storage-factory refinement, and `[Entity]` / `[FirstOrDefault]` / `[Queryable]` bound reads.
-- Presence diagnostics for Wolverine/Marten convention-alteration hooks, per-chain `Configure(HandlerChain)`, and Marten session listeners without interpreting policy or listener bodies.
-- Compound `Load*`, `Before*`, `After*`, `PostProcess*`, `Finally*`, and after-commit stages, with exact outgoing-message consequences retained on the owning entry point and explicit `WOLVERINE0020` loss.
-- Literal projection `PublishMessage(new TMessage(...))` side effects retained as Message/`Publishes` evidence, with `MARTEN0015` for unresolved payload flow.
-- Event wire configuration (`UseBinarySerializer<T>`, append mode, stream identity) and `RegisterValueType` concept nomination retained without fabricating event or concept representations.
-- Vogen concepts, primitive representations, authored validation hooks, nullable usages, and explicit loss diagnostics through the separately composed `Cratis.Screenplay.Generation.DotNet.Vogen` adapter.
-- Current store-agnostic Wolverine event-sourcing APIs and legacy Marten-specific APIs.
-- Target-aware exact current and legacy `IEventStream<T>` appends across multiple handler parameters, including commandless HTTP and metadata-only loaded streams, with per-binding identities and explicit diagnostics instead of first-stream guesses.
-- Bounded current and legacy Wolverine DCB evidence from authored `[DcbModel]` / `[BoundaryModel]` parameters, direct `EventTagQuery` fluent chains, exact boundary appends, and safe declarative returns, with `WOLVERINE0014`/`WOLVERINE0015` instead of invented stream topology.
-- Bounded authored Wolverine saga discovery for public concrete closed `Wolverine.Saga` state, grouped by message with Wolverine-compatible `SagaChain` admission. It preserves admitted role spellings and `Async` twins, constructor/returned-state creation constraints, collision-safe handler identities, exact correlation precedence (including inherited public members), cascades, timeouts, direct bus calls, and exact `MarkCompleted()` evidence. Saga state is excluded at every final HTTP query, message, and event admission boundary. `WOLVERINE0016` is a report-only realization/provenance diagnostic: Wolverine-managed lifecycle is intentionally not lowered because authored source does not safely establish a portable domain workflow. Screenplay uses ordinary Event Modeling building blocks; this is not a language-gap request, and generated `.play` bytes remain unchanged. `WOLVERINE0017` reports runtime-resolved correlation, while `WOLVERINE0018` reports rejected lifecycle shapes without inventing persistence or transport topology.
-- Markerless event/message discovery from actual framework usage.
-- Deterministic output without starting the application or connecting to PostgreSQL.
-- Explicit diagnostics whenever source behavior cannot be represented faithfully.
+The adapter recovers bounded Marten and Wolverine semantics — event stores, documents, aggregates, projections, queries, HTTP and message handlers, sagas, tenancy and event-wire configuration, and Vogen concepts — deterministically, without starting the application or connecting to PostgreSQL, and reports explicit diagnostics whenever source behavior cannot be represented faithfully. The complete goal list, including per-diagnostic evidence boundaries, lives in [`Documentation/goals.md`](Documentation/goals.md).
 
 ## Architecture
 
@@ -106,6 +90,21 @@ dotnet build Screenplay.CritterStack.slnx --configuration Release
 dotnet pack Screenplay.CritterStack.slnx --no-build --configuration Release -o Artifacts/NuGet
 ```
 
+## The Cratis ecosystem
+
+This project is part of [Cratis](https://www.cratis.io) — free, MIT-licensed tools for building event-sourced and CQRS applications.
+
+- **[Chronicle](https://github.com/Cratis/Chronicle)** — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. [Docs](https://www.cratis.io/chronicle/)
+- **Chronicle clients** — first-class [.NET SDK](https://github.com/Cratis/Chronicle), plus [TypeScript](https://github.com/Cratis/Chronicle.TypeScript), [Kotlin/Java](https://github.com/Cratis/Chronicle.Kotlin), and [Elixir](https://github.com/Cratis/Chronicle.Elixir); [Python](https://github.com/Cratis/Chronicle.Python) coming soon (pre-alpha). AI agents connect through the [Chronicle MCP server](https://github.com/Cratis/Chronicle.Mcp).
+- **[Arc](https://github.com/Cratis/Arc)** — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. [Docs](https://www.cratis.io/arc/)
+- **[Components](https://github.com/Cratis/Components)** — React components aligned with Arc patterns. [Docs](https://www.cratis.io/components/)
+- **[CLI](https://github.com/Cratis/cli) + Workbench** — inspect and diagnose Chronicle from the terminal or the browser. [Docs](https://www.cratis.io/cli/)
+- **Model-first layer (experimental)** — [Studio](https://github.com/Cratis/Studio), [Screenplay](https://github.com/Cratis/Screenplay), [Stage](https://github.com/Cratis/Stage), [Scene](https://github.com/Cratis/Scene), [Prologue](https://github.com/Cratis/Prologue)
+- **Supporting** — [Fundamentals](https://github.com/Cratis/Fundamentals), [Specifications](https://github.com/Cratis/Specifications), [Synopsis](https://github.com/Cratis/Synopsis), [Lens](https://github.com/Cratis/Lens), [Narrator](https://github.com/Cratis/Narrator), and free [AI tooling](https://github.com/Cratis/AI) (preview); [Ensemble](https://github.com/Cratis/Ensemble) coming soon (pre-release)
+- **[Samples](https://github.com/Cratis/Samples)** — runnable event sourcing and CQRS samples for the whole stack
+
+Everything Cratis publishes today is MIT licensed and free to use.
+
 ## License
 
 Screenplay.CritterStack is licensed under the [MIT license](LICENSE).

Source/DotNET/CritterStack/CritterStack.csproj

@@ -7,6 +7,7 @@
         <EnablePackageValidation>true</EnablePackageValidation>
         <PackageValidationBaselineVersion>0.22.0</PackageValidationBaselineVersion>
         <Description>Generates verified Cratis Screenplay definitions from Marten and Wolverine source</Description>
+        <PackageTags>cratis;event-sourcing;cqrs;screenplay;marten;wolverine;critterstack;interop</PackageTags>
     </PropertyGroup>
 
     <ItemGroup>