@cratis/pi 0.0.1

package/skills/cratis-chronicle-cli-operations/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: cratis-chronicle-cli-operations
+description: Inspect and operate a running Chronicle server with the cratis CLI - contexts and connection resolution, machine-readable output, failed partitions, observers, event sequences, read models, projections and jobs, and the authorization discipline for replay, retry, quarantine clearing and other mutations. Use when the question is about the state of a live store rather than source code. Do not use to diagnose a defect that reproduces locally in source.
+license: MIT
+---
+
+# Operate a running Chronicle with the `cratis` CLI
+
+Source code says what *should* happen. When the question is what *is* happening
+in a live store — a projection that will not move, an observer that stopped, an
+event you are not sure was appended — read the server instead of the code.
+
+## Verified product sources
+
+This skill is verified against these exact sources:
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Cli` | `2.4.0` | the `cratis` command, its contexts, output formats, and command tree |
+| `Cratis.Chronicle` | `16.45.2` | the observer, partition, sequence, and job concepts the CLI reads |
+
+The CLI ships a **versioned machine-readable catalog of its own surface**, and
+that catalog is the authority for exact command names on the installed version:
+
+```bash
+cratis llm-context          # every command, option and argument as JSON
+cratis llm-context --schema # the JSON Schema for that document
+cratis <group> --help       # the same, one group at a time
+```
+
+Do not guess a command name from this file. This skill covers *when to reach for
+the CLI and how to read what comes back*; the catalog covers *what to type*.
+
+## Install and set up
+
+`cratis` is a .NET tool published as `Cratis.Cli` with the command name
+`cratis`. Install it with `dotnet tool install -g Cratis.Cli`, or through
+Homebrew, or from a release binary. Follow with `cratis completions install`.
+
+Once per project, so every agent working it can reach the store:
+
+```bash
+cratis init                 # detects the AI tools in use and writes project context
+cratis init --refresh       # re-capture after upgrading the CLI
+```
+
+Two things worth knowing before running it:
+
+- The embedded catalog is a **snapshot**, not a live lookup. After a CLI upgrade
+  it still describes the older surface; `cratis init` reports the mismatch and
+  `--refresh` fixes it.
+- If the repository's instruction file is supplied by a shared package or a
+  generated adapter, pass `--no-context`. Keep project-specific Chronicle
+  connection guidance in a repository-owned project context file; never patch
+  packaged or generated bytes.
+
+## Reach the right server
+
+The connection string resolves in this exact order:
+
+1. `--server <CONNECTION_STRING>`
+2. the `CHRONICLE_CONNECTION_STRING` environment variable
+3. the active context's server in `~/.cratis/config.json`
+4. `chronicle://localhost:35000`
+
+Credentials are composed separately, and only when the resolved string carries
+no embedded `user:pass@` and no `apiKey=`: a cached access token first, then the
+context's client id and secret.
+
+Prefer a named context over repeating a connection string:
+
+```bash
+cratis context create <name> --server chronicle://<host>:35000
+cratis context set <name>
+cratis context show
+```
+
+A context also carries `--event-store` and `--namespace` defaults; both can be
+overridden per command with `-e` and `-n`. The event store defaults to
+`default` and the namespace to `Default`.
+
+**Be deliberate about which store you are pointed at.** The same commands read
+production and a local container, and several of them mutate. `cratis context
+show` before anything that writes; `--debug` prints the resolved config path,
+context, redacted connection string, and RPC timing to stderr.
+
+## Choose the output format
+
+There is one output flag, `-o` / `--output`, with values `table`, `plain`,
+`json`, `json-compact`, and `auto`. **There is no `--json` flag.**
+
+- `auto` (the default) resolves to `json-compact` when an AI-agent environment
+  is detected, `plain` when `NO_COLOR` is set, `json` when stdout is redirected,
+  and `table` otherwise.
+- `-q` / `--quiet` prints identifiers only, one per line — what you want when
+  piping one command into another. Combined with a JSON format it yields a JSON
+  array of identifiers.
+- Prefer `plain` for large listings; JSON repeats every field name on every row.
+  Prefer `json`/`json-compact` for `show`/`get` commands where you need the
+  nested structure.
+
+Exit codes are stable and worth branching on: `0` success, `1` not found, `2`
+connection error, `3` server error, `4` authentication error, `5` validation
+error.
+
+## Where to look
+
+| Question | Where to look |
+| --- | --- |
+| Is the server healthy at all? | `cratis chronicle diagnose` (exit code 3 when unhealthy) |
+| Why has this read model stopped updating? | `chronicle failed-partitions list --observer <id>` — the error is on the partition, not in the log |
+| An observer is quarantined — why? | `chronicle failed-partitions show <observer> <partition> --detailed`, with attempt history |
+| Did this event actually get appended? | `chronicle events get --event-type <type> --event-source-id <id>`, or `chronicle events tail` |
+| What is this event's shape in the store? | `chronicle event-types list`, then `chronicle event-types show <type>` |
+| Is this projection registered? | `chronicle projections list`, then `chronicle projections show <id>` |
+| What does the read model actually hold? | `chronicle read-models get <read-model> <key>`, or `read-models instances` |
+| Is a replay or migration still running? | `chronicle jobs list`, then `chronicle jobs get <id>` |
+| What does the server itself recommend? | `chronicle recommendations list` |
+
+Inspection commands are read-only: `diagnose`, `version`, `event-stores list`,
+`namespaces list`, `event-types list|show`, `events get|tail`, `observers
+list|show`, `failed-partitions list|show`, `projections list|show`,
+`read-models list|instances|get|snapshots|occurrences`, `jobs list|get`,
+`recommendations list`, `subscriptions list`, `identities list`, `users list`,
+`applications list`, and `auth status`.
+
+## Read what comes back
+
+- **A failed partition does not retry itself.** It stays failed until something
+  clears it, so a stale value is permanent rather than slow. That distinction is
+  the whole diagnosis: "not arrived yet" and "will never arrive" look identical
+  from the outside.
+- **Fix the cause before replaying.** Replaying into an unfixed handler fails the
+  same way and buries the original error under a newer one.
+- **A quarantined observer does not resume by itself.** Clearing the quarantine
+  is an explicit operation, and it is the last step, not the first.
+
+## Before you change anything
+
+Default to read-only inspection. A request to diagnose a live store does not
+authorize replay, retry, removal, quarantine clearing, or another mutation.
+
+These commands mutate the running store:
+
+- `chronicle observers replay`, `replay-partition`, `retry-partition`,
+  `clear-quarantine`
+- `chronicle jobs stop`, `chronicle jobs resume`
+- `chronicle recommendations perform`, `chronicle recommendations ignore`
+- `chronicle subscriptions add`, `chronicle subscriptions remove`
+- `chronicle users add`, `chronicle users remove`
+- `chronicle applications add`, `chronicle applications remove`
+
+Before any of them:
+
+1. Name the exact server context, event store, namespace, observer, partition,
+   event sequence, or job that will change.
+2. Capture its exact pre-state and the failure evidence that justifies the
+   operation.
+3. Prepare the repository-approved inverse or safe compensation when one exists;
+   stop when the effect cannot be safely reversed unless the owner separately
+   authorizes that irreversible operation.
+4. Show the dry run and obtain explicit authorization for that exact target and
+   action.
+5. Re-read the target immediately before mutation and stop on drift.
+
+### Two confirmation traps
+
+**Confirmation prompts do not fire when stdout is not a terminal.** The CLI
+treats a non-interactive session as an implicit yes, so a destructive command
+run from a script, a pipeline, or an agent harness proceeds without `-y` and
+without asking. Never rely on the prompt as the safety mechanism — the
+authorization above is the safety mechanism.
+
+**Not every mutating command prompts, even interactively.** `jobs stop` and
+`jobs resume` describe themselves as prompting for confirmation, but no prompt
+exists in the implementation. `users add`, `applications add`, and
+`subscriptions add` do not prompt either.
+
+Reaching for `--yes` to silence a prompt you have not read is how the wrong
+store gets replayed. A failed partition you have not yet explained is not a
+thing to clear: read it, fix the handler, then replay. Clearing it first
+destroys the evidence and the same failure returns on the next event.
+
+## What the CLI cannot do
+
+There is no `delete`, `purge`, `redact`, or `revise` command. Event redaction
+and revision are browser Workbench operations. Treat a request to "remove an
+event with the CLI" as a request that needs a different tool and a separate
+authorization.
+
+## Related
+
+- The terminal Workbench (`cratis chronicle workbench`) presents the same
+  read-only data as a navigable full-screen view; reach for it when you are
+  exploring rather than answering one question.
+- The browser Workbench owns redaction, revision, and event-type authoring.
+- Source-level diagnosis belongs in the application's own diagnostic workflow;
+  start there when the symptom reproduces locally, and start here when it is
+  only visible on a running server.

package/skills/cratis-chronicle-client-dotnet/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-chronicle-client-dotnet/SKILL.md

@@ -0,0 +1,433 @@
+---
+name: cratis-chronicle-client-dotnet
+description: Talk to a Chronicle server from a standalone .NET application with the Cratis.Chronicle client - connection strings, ChronicleClient construction outside any host, AddCratisChronicle for a worker or ASP.NET host, [EventType] records, IEventSequence.Append, reactors and reducers found by assembly scanning, the connection lifecycle and registration wait, and the client/server compatibility check. Use when a console, worker, or service app connects to Chronicle directly. Do not use for Arc applications, the Chronicle kernel, or the Kotlin, TypeScript, and Elixir clients.
+license: MIT
+---
+
+# The Chronicle client for .NET
+
+`Cratis.Chronicle` is a **standalone client SDK**. A console app, a worker, or a
+service constructs a client, asks it for an event store, and appends or observes.
+There is no host requirement and no application architecture imposed.
+
+> **This is not the Arc integration.** In an Arc application, Chronicle is wired
+> in for you and commands return events that Arc appends. Everything below is the
+> layer underneath: what an application that is *not* Arc has to do itself.
+
+## Verified product sources
+
+This skill is verified against the `Cratis/Chronicle` repository at tag
+`v17.0.1`, whose client sources are byte-identical to `16.45.2` for every public
+type cited here except the compatibility check noted below.
+
+| Package | Line | Purpose |
+| --- | --- | --- |
+| `Cratis.Chronicle` | `17.x` | `ChronicleClient`, `IEventStore`, `[EventType]`, observers |
+| `Cratis.Chronicle.Connections` | `17.x` | `ChronicleConnectionString`, connection lifecycle |
+| `Cratis.Chronicle.AspNetCore` | `17.x` | ASP.NET Core wiring, header/subdomain namespace resolvers |
+| `Cratis.Chronicle.Testing` | `17.x` | in-process scenarios |
+| `Cratis.Chronicle.CodeAnalysis` | `17.x` | the analyzers, a **separate opt-in** package |
+
+Take the exact version from nuget.org. The version in source is a `1.0.0`
+placeholder injected at pack time (`Source/Directory.Build.props`), so the
+repository never carries the real number. Reverify before claiming support for a
+version you have not checked.
+
+## Which package
+
+```shell
+dotnet add package Cratis.Chronicle              # console / worker service
+dotnet add package Cratis.Chronicle.AspNetCore   # ASP.NET Core
+```
+
+`Cratis.Chronicle.CodeAnalysis` is **not** pulled in by `Cratis.Chronicle`. Add
+it deliberately — it is what warns about the mistakes an event model makes
+silently, such as a nullable event property.
+
+## Connecting
+
+### The smallest real thing
+
+```csharp
+using Cratis.Chronicle;
+using Cratis.Chronicle.Connections;
+
+using var client = new ChronicleClient(ChronicleConnectionString.Development);
+var eventStore = await client.GetEventStore("<EventStoreName>");
+```
+
+That is the compiled documentation snippet verbatim
+(`Documentation/client-snippets/get-started/console/connect.md`). Those snippet
+files are compiled in CI against the real client projects, which makes them the
+safest source of .NET Chronicle example code in existence — prefer them over
+prose documentation.
+
+`IChronicleClient` — `Source/Clients/DotNET/IChronicleClient.cs:11`:
+
+| Member | Line |
+| --- | --- |
+| `ChronicleOptions Options { get; }` | `:16` |
+| `ICausationManager CausationManager { get; }` | `:21` |
+| `Task<IEventStore> GetEventStore(EventStoreName name, EventStoreNamespaceName? @namespace = default)` | `:32` |
+| `Task<IEnumerable<EventStoreName>> GetEventStores(CancellationToken cancellationToken = default)` | `:39` |
+| `void EvictEventStores()` | `:53` |
+
+**There is no `IChronicleClient.Connect`.** Connecting happens inside
+`GetEventStore`, which discovers artifacts and then connects
+(`Source/Clients/DotNET/ChronicleClient.cs:403-409`). When you do need the
+connection explicitly — in a worker's `ExecuteAsync`, for instance — it is
+`eventStore.Connection.Connect()`.
+
+`ChronicleClient` is `IDisposable`
+(`Source/Clients/DotNET/ChronicleClient.cs:30`) with five public constructors
+(`:76`, `:85`, `:94`, `:110`, `:183`). The one that matters for a real
+application is `:110`:
+
+```csharp
+public ChronicleClient(
+    ChronicleOptions options,
+    IClientArtifactsProvider? artifactsProvider = null,
+    IServiceProvider? serviceProvider = null,
+    IIdentityProvider? identityProvider = null,
+    ICorrelationIdAccessor? correlationIdAccessor = null,
+    IEventStoreNamespaceResolver? namespaceResolver = null,
+    ILoggerFactory? loggerFactory = null,
+    INamingPolicy? namingPolicy = null)
+```
+
+The canonical standalone sample uses it — `Samples/SimpleConsole/Program.cs:28-33`:
+
+```csharp
+var options = ChronicleOptions.FromConnectionString("chronicle://chronicle-dev-client:chronicle-dev-secret@localhost:35000");
+options.DefaultSinkTypeId = sinkType;
+
+using var client = new ChronicleClient(options, loggerFactory: loggerFactory);
+var store = await client.GetEventStore("TestStoreCS");
+```
+
+### Options
+
+`ChronicleOptions` — `Source/Clients/DotNET/ChronicleOptions.cs`. Statics:
+`FromConnectionString(string)` (`:191`), `FromConnectionString(ChronicleConnectionString)`
+(`:198`), `FromDevelopmentConnectionString()` (`:214`). The parameterless
+constructor (`:40`) is the development connection string.
+
+Options worth knowing: `AutoDiscoverAndRegister` (default `true`, `:90`),
+`ConnectTimeout` (default 5 seconds, `:95`), `SkipKeepAlive` (`:127` — turn the
+watchdog off for a short-lived client), `DefaultSinkTypeId` (default
+`WellKnownSinkTypes.MongoDB`), `Tls`, `Authentication`, `RegistrationRetry`.
+
+### Connection strings, not URLs
+
+**There is no `ChronicleUrl` type and no microservice id.** The identity of a
+connection is a connection string plus an event store name and optionally a
+namespace. `ChronicleConnectionString` lives in `Cratis.Chronicle.Connections`
+(`Source/Clients/Connections/ChronicleConnectionString.cs:33`):
+
+```
+chronicle://host[:port]/?opts
+chronicle://user:pass@host[:port]/?opts
+chronicle+srv://host/?opts
+```
+
+Default port `35000`. `Default` is `chronicle://localhost:35000` (`:48`);
+`Development` adds the `chronicle-dev-client` / `chronicle-dev-secret`
+credentials (`:57`). Query options: `apiKey`, `auth`, `skipTlsValidation`,
+`loadBalancer`, `srvNameServer`, `certificatePath`, `certificatePassword`
+(`ChronicleConnectionStringBuilder.cs:27-36`). There is an implicit conversion
+from `string` (`:158`) and a `Redacted` form for logging (`:152`).
+
+> **Certificate validation is skipped by default, and that is deliberate.** The
+> Chronicle server always serves TLS, generating a self-signed certificate on
+> every start when none is configured, so a development pair connects with no
+> setup — the rationale is written out at `ChronicleClient.cs:141-146`. **A
+> production connection string must set `skipTlsValidation=false`** (or
+> `Tls.SkipCertificateValidation = false`) against a server whose certificate is
+> actually verifiable.
+
+### In a host
+
+```csharp
+var builder = Host.CreateApplicationBuilder(args);
+builder.AddCratisChronicle(options => options.EventStore = "<EventStoreName>");
+builder.Services.AddHostedService<<WorkerName>>();
+await builder.Build().RunAsync();
+```
+
+`AddCratisChronicle` is an extension on **`IHostApplicationBuilder`**
+(`Source/Clients/DotNET/ChronicleHostApplicationBuilderExtensions.cs:28`) and binds
+the `Cratis:Chronicle` configuration section by default (`:25`, `:37`), with
+`ValidateDataAnnotations().ValidateOnStart()`. The bound type is
+`ChronicleClientOptions : ChronicleOptions`, which adds a `[Required] EventStore`
+and an optional `EventStoreNamespaceResolverType`.
+
+> **`AddCratisChronicle` on `IServiceCollection` does not exist**, despite what
+> `Documentation/clients/dotnet/getting-started.md:61` shows. The real extensions
+> are on `IHostApplicationBuilder`, `WebApplicationBuilder` (in the AspNetCore
+> package), and Aspire's `IDistributedApplicationBuilder`. `IHostBuilder.AddCratisChronicle()`
+> also exists but only registers concept type converters
+> (`Source/Clients/DotNET/Hosting/HostBuilderExtensions.cs:18-23`) — it is not
+> the wiring entry point.
+
+`IChronicleBuilder` extensions are exactly five:
+`WithArtifactsProvider`, `WithIdentityProvider`, `WithCorrelationIdAccessor`,
+`WithNamespaceResolver`, `WithCamelCaseNamingPolicy`
+(`Source/Clients/DotNET/ChronicleBuilderExtensions.cs`). **There is no
+`WithClaimsBasedNamespaceResolver`**, despite a doc comment at
+`ChronicleOptions.cs:141` referring to one. Pass the resolver instead:
+`new ChronicleClient(options, namespaceResolver: new ClaimsBasedNamespaceResolver("tenant_id"))`.
+
+## The client and the server check each other
+
+Since Chronicle 17 the compatibility check is a server-side RPC, and **the client
+runs it automatically inside `Connect()`** —
+`Source/Clients/Connections/ChronicleConnection.cs:310` calls
+`CheckCompatibility` (`:405`), sending the client type, client version, protocol
+version, and the descriptor set its contracts package was built with (`:411-417`).
+The rationale is at `:400-404`: Chronicle has clients in four languages and only
+some can build a descriptor set at runtime, so each ships the one it was built
+with and the server does the single comparison.
+
+Behavior you can rely on:
+
+- A server too old to have the RPC answers `Unimplemented`, and the client falls
+  back to the previous client-side exchange (`:419-425`) — upgrading the client
+  does not silently drop the check.
+- Any other transport error is **logged and ignored** (`:426-432`), on the stated
+  reasoning that failing to ask says nothing about whether the two sides agree.
+- A genuine mismatch throws `IncompatibleServerException`
+  (`Source/Clients/Connections/IncompatibleServerException.cs:10`) whose message
+  names the server address, its version, its protocol version, and the specific
+  incompatibilities (`:436-443`).
+
+The client identifies itself as `".NET"`
+(`Source/Clients/Connections/ChronicleClientIdentity.cs:22`) with its assembly
+informational version (`:27`) and the contracts protocol version (`:32`).
+
+## Event types
+
+```csharp
+using Cratis.Chronicle.Events;
+
+/// <summary><What happened, in the past tense.></summary>
+[EventType]
+public record <EventName>(<Type> <Property>);
+```
+
+`EventTypeAttribute` is in `Cratis.Chronicle.Events` —
+`Source/Clients/DotNET/Events/EventTypeAttribute.cs:20`:
+
+```csharp
+public sealed class EventTypeAttribute(string id = "", uint generation = EventTypeGeneration.FirstValue) : Attribute
+```
+
+**Two arguments only** — `id` (empty means the type name) and `generation`
+(`EventTypeGeneration.FirstValue` is `1U`). There is no `isPublic` parameter.
+`AttributeUsage` is `AttributeTargets.Class`, which records satisfy.
+
+For a new event, pass nothing: the type name is the identifier. Use `generation`
+only when evolving a contract that already exists, and prefer
+`EventTypeGenerationForAttribute<TEventType>` over a second `[EventType]` — the
+guidance is in the attribute's own remarks (`EventTypeAttribute.cs:14-18`).
+
+## Appending
+
+`IEventLog : IEventSequence` is a marker
+(`Source/Clients/DotNET/EventSequences/IEventLog.cs:9`); the surface is on
+`IEventSequence` (`Source/Clients/DotNET/EventSequences/IEventSequence.cs:14`):
+
+```csharp
+Task<AppendResult> Append(                                   // :115
+    EventSourceId eventSourceId,
+    object @event,
+    EventStreamType? eventStreamType = default,
+    EventStreamId? eventStreamId = default,
+    EventSourceType? eventSourceType = default,
+    CorrelationId? correlationId = default,
+    IEnumerable<string>? tags = default,
+    ConcurrencyScope? concurrencyScope = default,
+    DateTimeOffset? occurred = default,
+    Subject? subject = default);
+
+Task<AppendManyResult> AppendMany(EventSourceId eventSourceId, IEnumerable<object> events, /* same optionals */);  // :144
+Task<AppendManyResult> AppendMany(IEnumerable<EventForEventSourceId> events, /* ... */);                            // :167
+```
+
+```csharp
+var result = await eventStore.EventLog.Append(<eventSourceId>, new <EventName>(<value>));
+if (!result.IsSuccess)
+{
+    // result.ConstraintViolations, result.ConcurrencyViolation, result.Errors
+}
+```
+
+- `EventSourceId` is a `record EventSourceId(string Value) : ConceptAs<string>`
+  with implicit conversion from `string` and `Guid`
+  (`Source/Clients/DotNET/Events/EventSourceId.cs:12`, `:37`, `:44`).
+- `AppendResult` carries `SequenceNumber`, `IsSuccess`,
+  `HasConstraintViolations`, `HasConcurrencyViolations`, `HasErrors`,
+  `ConstraintViolations`, `ConcurrencyViolation`, `Errors`, and the routing facts
+  (`Source/Clients/DotNET/EventSequences/AppendResult.cs:13-59`).
+- The `IEnumerable<EventForEventSourceId>` overload is the way to append across
+  several event sources in one batch.
+- **There is no `AppendAnonymous`.** It does not exist anywhere in the product.
+
+Reading back is on the same interface: `GetForEventSourceIdAndEventTypes` (`:51`),
+`HasEventsFor` (`:58`), `GetFromSequenceNumber` (`:67`), `GetNextSequenceNumber`
+(`:73`), `GetTailSequenceNumber` (`:84`). Erasure is `Redact` (`:191`, `:200`).
+
+Several appends as one unit:
+
+```csharp
+var unitOfWork = eventStore.UnitOfWorkManager.Begin(CorrelationId.New());
+await eventStore.EventLog.Transactional.Append(<eventSourceId>, new <EventName>(<value>));
+await unitOfWork.Commit();
+```
+
+`ITransactionalEventSequence` returns `Task`, not a result
+(`Source/Clients/DotNET/EventSequences/ITransactionalEventSequence.cs:33`); the
+results live on the unit of work.
+
+## Observing
+
+| Artifact | Shape | Source |
+| --- | --- | --- |
+| Reactor | marker `IReactor` (empty interface), `[Reactor]` optional | `Reactors/IReactor.cs:9`, `Reactors/ReactorAttribute.cs:14` |
+| Reducer | `IReducerFor<TReadModel>` | `Reducers/IReducerFor.cs:10` |
+| Projection | `IProjectionFor<TReadModel>` with `Define(IProjectionBuilderFor<TReadModel>)` | `Projections/IProjectionFor.cs:10-17` |
+| Model-bound projection | attributes on the read model | `Projections/ModelBound/` |
+| Read model reactor | marker `IReadModelReactor`, methods `Added`/`Modified`/`Removed` | `ReadModels/IReadModelReactor.cs:10-18` |
+
+**A reactor handler is found by its first parameter's type**, and further
+parameters are resolved as dependencies — `EventContext`, a read model, a service
+(`Source/Clients/DotNET/Reactors/EventHandlerMethods.cs:21-46`, `:89-103`). The
+return may be `Task`, `void`, or a side-effect event type.
+
+```csharp
+using Cratis.Chronicle.Events;
+using Cratis.Chronicle.Reactors;
+
+public class <ReactorName>(<IDependency> <dependency>) : IReactor
+{
+    public async Task <AnyMethodName>(<EventName> @event, EventContext context)
+    {
+        await <dependency>.<DoSomething>(context.EventSourceId, @event.<Property>);
+    }
+}
+```
+
+> **There is no `[Observer]` attribute and no `IObserver` client artifact.**
+> "Observer" is the kernel's umbrella term for a projection, reducer, or reactor;
+> it is not something you write. `Source/Clients/DotNET/Observation/` holds
+> `ObserverId`, `ObserverRunningState`, and failed-partition types only.
+
+Read models are queried through `eventStore.ReadModels`
+(`Source/Clients/DotNET/ReadModels/IReadModels.cs`):
+`GetInstanceById<TReadModel>(ReadModelKey, ReadModelSessionId?)` (`:38`),
+`GetInstances<TReadModel>(EventCount?)` (`:55`),
+`GetSnapshotsById<TReadModel>` (`:63`),
+`IObservable<ReadModelChangeset<TReadModel>> Watch<TReadModel>()` (`:70`).
+
+## Discovery
+
+Artifacts are found by **assembly scanning**, with no registration call and no DI
+container required. `DefaultClientArtifactsProvider.Default` composes the
+project-referenced and package-referenced assemblies
+(`Source/Clients/DotNET/DefaultClientArtifactsProvider.cs:35`), and the
+predicates are exactly (`:230-238`):
+
+| Kind | Predicate |
+| --- | --- |
+| event types | `HasAttribute<EventTypeAttribute>()` or `HasAttribute<EventTypeGenerationForAttribute>()` |
+| projections | `HasInterface(typeof(IProjectionFor<>))` |
+| model-bound projections | `HasModelBoundProjectionAttributes()` |
+| reactors | `HasInterface<IReactor>()` and not generic |
+| read model reactors | `HasInterface<IReadModelReactor>()` and not generic |
+| reducers | `HasInterface(typeof(IReducerFor<>))` and not generic |
+
+Explicit registration is available per family as an alternative —
+`IEventTypes.Register`, `IConstraints.Register`, `IProjections.Register`,
+`IReducers.Register`, `IReactors.Register<TReactor>()`,
+`IReadModels.Register<TReadModel>()` — and is what you use with
+`AutoDiscoverAndRegister = false`.
+
+## Lifecycle
+
+- **Registration is wired to the connection, not called by you.**
+  `EventStore.cs:265-268` subscribes `RegisterAll` to `Connection.Lifecycle.OnConnected`
+  when `autoDiscoverAndRegister` is on, so a reconnect re-registers everything.
+- `DiscoverAll()` does event types first, then constraints, reactors, reducers,
+  projections, and seeding in parallel (`EventStore.cs:349-362`). `RegisterAll()`
+  is single-flighted with jittered backoff and a background retry loop (`:373-379`).
+- **Wait with `WaitForRegistration`, not by polling `IsConnected`.**
+  `RegistrationWaitExtensions.WaitForRegistration(this IEventStore, TimeSpan? timeout = default)`
+  (`Source/Clients/DotNET/Registrations/RegistrationWaitExtensions.cs:42`, default
+  5 seconds) exists precisely for this, and its own remarks warn against the
+  `IConnectionLifecycle.IsConnected` alternative (`:34-39`). Connected is not
+  registered.
+- **Keepalive is a bidirectional stream plus a watchdog.** The watchdog monitors
+  every `MonitorIntervalMilliseconds = 1000`
+  (`Source/Clients/Connections/ConnectionWatchdog.cs:34`) and a keepalive that
+  falls more than 5 seconds behind is treated as a lost connection, with
+  reconnect backoff capped at 30 seconds. **The failure mode is silence, not an
+  exception** — appends keep working while observers go quiet.
+- `Dispose()` disposes read model reactors for created stores, cancels the owned
+  connection, and disposes the connection
+  (`Source/Clients/DotNET/ChronicleClient.cs:225-246`).
+
+## What a standalone app owns that a host would have supplied
+
+Every one of these has a silent default. Read them as a checklist, because the
+defaults are reasonable for a sample and wrong for a service
+(`ChronicleClient.cs:121-127`):
+
+| Concern | Default when you pass nothing |
+| --- | --- |
+| `IClientArtifactsProvider` | `DefaultClientArtifactsProvider.Default` — full assembly scan |
+| `IServiceProvider` | `DefaultServiceProvider`, which activates everything through `Activator.CreateInstance` (`DefaultServiceProvider.cs:41`) |
+| `IIdentityProvider` | `BaseIdentityProvider` |
+| `ICorrelationIdAccessor` | `CorrelationIdAccessor` |
+| `IEventStoreNamespaceResolver` | `DefaultEventStoreNamespaceResolver` — always `"Default"` |
+| `ILoggerFactory` | `new LoggerFactory()` — **a silent one** |
+| Configuration binding | none; there is no `Cratis:Chronicle` section without a host |
+
+The `IServiceProvider` default is the sharp one: **a reactor or reducer with
+constructor dependencies is default-constructed** unless you pass a real
+container. Pass one, or keep observers dependency-free.
+
+The AspNetCore package additionally registers `AddUnitOfWork()`,
+`AddCompliance()`, `AddCausation()`, `AddChronicleHealthCheck()`, and
+`UseCratisChronicle()` — none of which the base package gives you.
+
+**Keep the process alive.** Observation is a live gRPC duplex stream; a console
+app that appends and returns from `Main` never sees a reactor run.
+
+## Common pitfalls
+
+| Pitfall | Why it bites |
+| --- | --- |
+| Looking for `IChronicleClient.Connect` | It does not exist; `GetEventStore` connects, and `eventStore.Connection.Connect()` is the explicit form |
+| `services.AddCratisChronicle(...)` | Not a real extension; it is on `IHostApplicationBuilder`/`WebApplicationBuilder` |
+| `builder.WithClaimsBasedNamespaceResolver()` | Not a real extension; pass the resolver to the client instead |
+| Shipping the default TLS behavior to production | Certificate validation is skipped by default |
+| Constructing a client without an `ILoggerFactory` | You get a silent logger and lose every diagnostic the client emits |
+| A reactor with constructor dependencies and no `IServiceProvider` | It is built by `Activator.CreateInstance` with no arguments |
+| Polling `IsConnected` to know it is ready | Connected is not registered; use `WaitForRegistration` |
+| Treating a quiet reactor as "no events yet" | Keepalive loss stops observers while appends keep succeeding |
+| Returning from `Main` after appending | The observation stream dies with the process |
+| Expecting the analyzers | `Cratis.Chronicle.CodeAnalysis` is a separate opt-in package |
+| Copying a version out of the repository | It is a `1.0.0` placeholder; take it from nuget.org |
+
+## Verify
+
+- The package version is the one you intended, taken from nuget.org.
+- The connection succeeds and no `IncompatibleServerException` is thrown — and if
+  the compatibility check was skipped, you know why (a transport error is logged
+  and ignored by design).
+- A production connection string sets `skipTlsValidation=false`.
+- An `ILoggerFactory` is supplied, and client logs are visible.
+- Observers that take dependencies get a real `IServiceProvider`.
+- Readiness is established with `WaitForRegistration`, not with `IsConnected`.
+- The process stays alive for as long as observation is expected.
+- The build is clean and the specifications pass against the verified package
+  version.

package/skills/cratis-chronicle-client-elixir/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.