@cratis/pi 7.34.1 → 7.36.0

package/package/corpus/skills/cratis-arc-spring-data-kotlin/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: cratis-arc-spring-data-kotlin
+description: Use Spring Data JPA or MongoDB with Kotlin or Java Arc read models — repository-backed queries and paging, command current-state resolution, observable snapshots, concept converters, certified tenant storage and explicit transaction opt-ins. Use when wiring JVM Arc persistence or database-backed observations. Do not use for Chronicle projections, C# EF Core, query transport alone, or authentication and tenant resolution alone.
+license: MIT
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Use Spring Data with JVM Arc
+
+Keep Spring Data responsible for persistence and Arc responsible for the
+model-bound command/query pipeline. Repository injection alone does not isolate
+tenants or turn a repository into an observable source.
+
+## Verified product sources
+
+Verified at `Arc.Kotlin v7.7.0`: `Integrations/SpringDataJpa`,
+`Integrations/SpringDataMongo` (observable query services/extensions, contextual
+read-model providers, tenant access and converters) and
+`Documentation/guides/spring-data/*.mdx`.
+Add `io.cratis:arc-spring-data-jpa:7.7.0` or
+`io.cratis:arc-spring-data-mongodb:7.7.0`; both include the Arc Spring Boot
+starter and corresponding Spring Data starter. Spring owns repository discovery,
+datasource/entity manager, Mongo client and their standard configuration.
+
+## Query a mapped read model
+
+JPA example (requires the application's normal JPA entity/no-arg setup):
+
+```kotlin
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import io.cratis.arc.artifacts.FromServices
+import io.cratis.arc.artifacts.ReadModel
+import jakarta.persistence.Entity
+import jakarta.persistence.Id
+import org.springframework.data.jpa.repository.JpaRepository
+
+@Entity
+@ReadModel
+data class TaskView(@Id val id: String = "", val title: String = "") {
+    companion object {
+        @JvmStatic
+        fun all(@FromServices tasks: TaskViewRepository): List<TaskView> = tasks.findAll()
+    }
+}
+
+interface TaskViewRepository : JpaRepository<TaskView, String>
+```
+
+The same injection pattern works with `MongoRepository`, fragments or an
+application query service. Java uses static query methods on its mapped type.
+Protect the query with the application's authorization policy; mapping does
+not make it safe to expose anonymously.
+
+A query can declare exact non-null Spring Data Commons `Pageable` and `Sort`.
+KSP binds them from the captured `QueryRequest`, not thread-local request scope.
+Such queries must return exact `org.springframework.data.domain.Page<T>`;
+Arc normalizes it into `QueryPage<T>` before renderers, preserving pre-page
+total count. Page size zero means unpaged; blank sort field means unsorted.
+Do not confuse Spring Data `Page<T>` with a nonexistent Arc `Page<T>`.
+
+## Current state in a command
+
+Mapped `@ReadModel` types are owned by contextual
+`CanResolveReadModelForCommand` providers. JPA claims `DECLARED` ownership;
+MongoDB claims `FALLBACK`, so an explicit JPA/Chronicle/application owner wins.
+Equal-strength claims fail startup. Registry-owned model parameters resolve
+before ordinary services, using the generated command key and captured tenant.
+Keys must already match the persistence identifier type, not need coercion.
+Missing required rows or keys yield `dependencyUnavailable`; nullable Kotlin
+parameters/Java `Optional` observe absence. Resolver failures remain exceptions.
+
+## Stream storage snapshots
+
+Mongo example excerpt inside a `TaskView` companion object (the type has an
+`active` property and is Mongo-mapped):
+
+```kotlin
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import io.cratis.arc.springdata.mongodb.MongoObservableQuery
+import io.cratis.arc.springdata.mongodb.observe
+import kotlinx.coroutines.flow.Flow
+import org.springframework.data.mongodb.core.query.Criteria
+
+@JvmStatic
+fun active(@FromServices queries: MongoObservableQuery): Flow<List<TaskView>> =
+    queries.observe<TaskView>(Criteria.where("active").`is`(true))
+```
+
+`observe`, `observeList`, `observeSingle`, `observeById`, `observeShared` are
+extensions on Arc's `MongoObservableQuery` or `JpaObservableQuery`, not foreign
+repositories or collections. Import the extensions from the store's package.
+Flows are cold and close their subscription on cancellation. `observeShared`
+explicitly shares one subscription and replays the latest complete snapshot.
+Java uses `observePublisher` or `MongoObservations`/`JpaObservations` helpers.
+
+MongoDB change streams require a replica set or sharded cluster; invalidations
+cause a fresh filtered snapshot so rows that stop matching disappear. JPA
+observations are **in-process only**: publish committed changes through
+`DatabaseChangePublisher`. There is no silent polling or cross-process JPA
+notification. A tenant label on a JPA notification is not storage isolation.
+
+## Tenant-bound storage and concepts
+
+Resolve/authenticate the tenant using `cratis-arc-identity-and-tenancy-kotlin`
+first. Then select certified isolated stores:
+
+- JPA: an application `JpaPersistenceUnitResolver` returns a `JpaPersistenceUnit`
+  certified for the requested tenant/namespace and mapped type.
+- Mongo: a `TenantAwareMongoOperationsResolver` returns `TenantMongoOperations`
+  for the exact tenant. Unknown tenants throw; mismatched certificates fail,
+  never fall back to a default database.
+- `TenantContextMongoAccess.operations()` resolves the ambient tenant on **each
+  call**, not at construction. Establish `withTenant` explicitly; the command
+  pipeline does not create this ambient scope for you. Java on a plain thread
+  uses `operationsForCurrentTenant()` inside `TenantContextBridge.withTenant`;
+  a Java command handler uses the explicit-tenant overload instead of blocking
+  inside its coroutine. The auto-configured access has no fallback tenant.
+
+Plain injected repositories are not automatically routed by tenant. Native
+collection access uses Arc's `NamingPolicy`, while Spring Data operations respect
+`@Document`; choose deliberately. For Chronicle projection collection alignment,
+read [../cratis-arc-command-kotlin/references/read-model-naming.md](../cratis-arc-command-kotlin/references/read-model-naming.md)
+when upgrading or changing names.
+
+Concept persistence needs store-specific converters: JPA attribute converters
+(or embedded ids for composite identity), Mongo concrete scalar read/write pairs.
+Do not persist a generic `ConceptAs` wrapper as an arbitrary object or assume a
+JSON converter also handles BSON/JPA. Read the tagged `concepts-jpa.mdx` and
+`concepts-mongodb.mdx` guides for the actual identifier type and converter registration.
+
+## Transactions are explicit, thread-bound opt-ins
+
+`cratis.arc.spring-data.jpa.command-transactions-enabled` and
+`cratis.arc.spring-data.mongodb.command-transactions-enabled` default to false.
+Enable only for a verified fixed store and identity-aligned transaction manager.
+Dynamic tenant stores are not auto-enrolled. Even enabled, command persistence
+must not suspend or switch threads: imperative Spring transactions are not
+coroutine-safe. They commit only a successful final `CommandResult` and roll
+back failures when completing on the opening thread.
+
+There is **no distributed transaction** across JPA, MongoDB and Chronicle.
+Chronicle completion follows local scopes, but a local store may already commit
+before another store or Chronicle fails. Define reconciliation for partial or
+indeterminate outcomes rather than claiming atomic cross-store success.
+
+## Verify
+
+- Run `./gradlew build`, pipeline specs via `cratis-arc-testing-kotlin`, and
+  real-store tests for converters, paging counts and tenant isolation.
+- Verify missing/unknown tenants cannot access the default store.
+- Exercise Mongo snapshots against a real replica set; an in-memory emulator
+  cannot prove change streams. Verify cancellation releases the cursor.
+- For JPA, verify committed notifications, rollback suppression and the intended
+  in-process boundary; test thread affinity before enabling transactions.
+
+Query transport: `cratis-arc-query-kotlin`. Chronicle projections:
+`cratis-chronicle-client-kotlin`, not a Spring Data observation.

package/package/corpus/skills/cratis-arc-testing-kotlin/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: cratis-arc-testing-kotlin
+description: Specify Kotlin or Java Arc commands and queries through real in-process pipelines with arc-testing — CommandScenario, QueryScenario, bounded ObservableQueryScenario collection, read-model pins, tenant resolution, and Chronicle append assertions. Use when writing or diagnosing JVM Arc pipeline specifications without Spring Boot or a kernel. Do not use for standalone Chronicle client tests, C# scenarios, or defining the command or query itself.
+license: MIT
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Specify Arc behavior on the JVM
+
+Use generated artifacts through the real pipelines, not hand-written handlers
+that bypass KSP wiring. `arc-testing` needs neither Spring Boot nor Docker.
+This is test support, not an alternative production host.
+
+## Verified product sources
+
+Verified at `Arc.Kotlin v7.7.0`: `Testing/src/main/kotlin/io/cratis/arc/testing`
+(`CommandScenario`, `QueryScenario`, `ObservableQueryScenario`, result assertions),
+`Integrations/Chronicle/ChronicleCommandScenario.kt`, and
+`Documentation/guides/testing.mdx`. Add
+`testImplementation("io.cratis:arc-testing:7.7.0")`; align it with the runtime,
+plugin and KSP version. The repository uses JUnit Jupiter `6.1.3`.
+
+## Choose the pipeline
+
+| Behavior | Scenario |
+| --- | --- |
+| Execute or validate a command | `CommandScenario(module, CommandType::class.java)` |
+| One-shot query | `QueryScenario<T>` selected by `FullyQualifiedQueryName` |
+| Streaming query | `ObservableQueryScenario<T>` with bounded `collect(maximumEmissions, timeoutMillis)` |
+
+Application specs select a generated `ArcArtifactModule`. Manual
+`CommandHandler`/`QueryPerformer` constructors are for framework tests.
+Arrange services, validators, authorization policies, filters, principal,
+tenant and correlation id on the scenario before executing it.
+
+Illustrative excerpt: `module` is the generated module; `CreateTask` and its
+`TaskRepository`/`TaskCreated` types are supplied by the application.
+
+```kotlin
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import io.cratis.arc.testing.CommandScenario
+
+val result = CommandScenario(module, CreateTask::class.java)
+    .addService(TaskRepository::class.java, repository)
+    .execute(CreateTask("Try Arc"))
+
+result.shouldSucceed().shouldHaveResponse(TaskCreated::class.java)
+```
+
+Command and one-shot query scenarios perform JSON round trips by default,
+including the module's registered derived types. Keep them enabled to exercise
+wire behavior. Disable them only for a deliberate pure/in-process assertion;
+serialization failures propagate to the test, not a successful result.
+Observable scenarios do not perform opening-argument or result-data round trips.
+
+## Pin current state, including absence
+
+- `withReadModel(type, value)` pins a type regardless of command key.
+- `withReadModelForKey(type, key, value)` proves key selection too; other keys
+  resolve to absence. Scalar keys match concept-wrapped keys after unwrapping.
+- A `null` pin is deliberate absence. Required parameters fail with
+  `dependencyUnavailable`; Kotlin nullable parameters receive `null`, and
+  Java `Optional` parameters receive `Optional.empty()`.
+- Pins claim ownership and win over fallback resolvers. Do not mix a global
+  pin and keyed pins for the same type. Use `addReadModelResolver` for computed state.
+
+## Assert the rejecting stage
+
+Use positive and negative assertions rather than only `shouldFail()`:
+`shouldBeAuthorized`/`shouldBeUnauthorized`, `shouldBeValid`/`shouldBeInvalid`,
+`shouldHaveErrors`/`shouldHaveNoErrors`.
+`shouldBeAuthorized().shouldBeInvalid()` states that authorization passed and
+a validation rule rejected the input.
+
+`CommandScenarioResult.shouldBeInvalid()` fails when all feedback is
+`dependencyUnavailable`: that normally means the test forgot a dependency,
+not that a rule ran. Pin or register it before asserting the rule. When missing
+dependencies are the intended behavior, assert
+`shouldHaveValidation(reason = ValidationResultReasons.DEPENDENCY_UNAVAILABLE)`.
+
+`withTenantResolution` takes a resolver and explicit request context on all
+three scenarios. The resolved tenant also becomes the namespace unless one is
+supplied. Test unresolved and unauthorized tenant selection as well as success;
+use `cratis-arc-identity-and-tenancy-kotlin` for the request contract.
+
+## Bound observable specifications
+
+One timeout budget covers opening and collection. Timeout/cancellation
+propagates and cancels cooperative upstream work; it is not a successful result.
+`maximumEmissions` is a cap, not a required count: a finite stream can finish
+empty or early. Chain `shouldHaveEmissionCount(expected)` when count matters.
+`addEmissionGuard` supplies per-emission checks; assert opening rejection with
+`shouldFail()` and terminal guard denial with `shouldTerminateUnauthorized()`.
+
+## Chronicle integration without a kernel
+
+Add the Chronicle starter (or `io.cratis:cratis`) alongside `arc-testing`.
+Its `CommandScenarioExtender` is found through `ServiceLoader` and supplies
+an in-memory event log automatically. `givenChronicle().events(id, event)`
+establishes prior history; `chronicle().shouldHaveAppendedEvent(id, Event::class.java)`
+checks the new append. Given events are excluded from `appendedEvents`.
+Arrange `constraintViolation(...)` or `concurrencyViolation(...)` to reject an
+append deterministically and assert `shouldHaveConstraintViolation(...)` or
+`shouldHaveConcurrencyViolation(...)`. Rejected appends are not appended events.
+This does not verify a real kernel constraint or storage integration.
+
+## Java and verification
+
+Use the closeable `BlockingCommandScenario` over a configured scenario for
+ordinary Java tests; configure pins, tenant resolution and Chronicle before
+constructing the bridge. `ChronicleCommandScenarios` exposes Kotlin extensions
+as Java statics. For asynchronous tests use `AsyncCommandScenario`,
+`AsyncQueryScenario`, `AsyncObservableQueryScenario` and a `JavaAsyncScope`.
+`usingExecutor` borrows an executor; `owningExecutorService` owns shutdown.
+Scenarios borrow the scope; close the owner after the test.
+`collectAsync` returns a `CompletionStage` with bounded collection. Timeout
+cancels the stage; callback-based `collect` does not deliver timeout callbacks.
+
+- Follow the `for_`/`when_` naming conventions in `kotlin.md`/`java.md`.
+- Run `./gradlew build` with warnings treated as errors and all affected specs.
+- Verify authorization, rejection, absence and failure paths that apply, not
+  only a successful response.
+- Run real-store integration checks separately when the behavior depends on
+  kernel constraints, persistence, transactions or change streams.
+
+For definition rather than tests: `cratis-arc-command-kotlin`,
+`cratis-arc-query-kotlin`, `cratis-arc-validation-kotlin`.

package/package/corpus/skills/cratis-arc-validation-kotlin/SKILL.md

@@ -14,16 +14,12 @@ that way; keep service calls, async work, and cross-member logic imperative.
 
 ## Verified product sources
 
-Verified against `Arc.Kotlin` at tag **`v7.3.0`**, re-verified at commit
-`d0aa6a4` (14 commits past the tag; `guides/commands.md`, `guides/validation.md`,
-and `guides/chronicle.md` are byte-for-byte unchanged since the tag).
-Documented consumer setup: JDK 17, Kotlin 2.4.20, KSP 2.3.12, Spring Boot
-4.1.x. `io.cratis:arc` supplies `io.cratis.arc.validation.FluentModelValidator`,
-`CommandValidator<T>`, `QueryValidator<T>`, `ConceptValidator<T>`,
+Verified against `Arc.Kotlin` at tag **`v7.7.0`**: JDK 17, Gradle 8.14.4,
+Kotlin 2.4.20, KSP 2.3.12, Spring Boot 4.1.1, JUnit Jupiter 6.1.3. `io.cratis:arc` supplies `io.cratis.arc.validation.FluentModelValidator`,
+`CommandValidator<T>`, nongeneric `QueryValidator`, `ConceptValidator<T>`,
 `ModelValidator<T>`, `ConceptValidationExclusion`, `IgnoreValidation`,
-`CommandFilter`, `QueryFilter`. The re-verification added the new
-"Reject at feature scope with a pipeline filter" section below, from the new
-`guides/pipeline-filters.md`.
+`CommandFilter`, `QueryFilter`. Sources: `queries/QueryValidator.kt`,
+`commands/CommandValidator.kt`, validation types and `guides/pipeline-filters.mdx`.
 
 ## Shared fluent rules — server and generated TypeScript
 
@@ -125,7 +121,7 @@ validated child roots still run.
 
 ## Server-only validators
 
-### `CommandValidator<T>` / `QueryValidator<T>`
+### `CommandValidator<T>`
 
 ```kotlin
 @Component
@@ -153,6 +149,39 @@ Java implementations use `BlockingCommandValidator`/`AsyncCommandValidator`
 with the matching `*Adapter`, published as an ordinary `CommandValidator`
 Spring bean — there is no second Java-specific discovery mechanism.
 
+### `QueryValidator` — request-based, not generic
+
+A query validator receives `QueryRequest` and `QueryContext`, not a typed
+command-style model. `queryName = null` matches every query; set a
+`FullyQualifiedQueryName` to restrict it to one query.
+
+```kotlin
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import io.cratis.arc.queries.FullyQualifiedQueryName
+import io.cratis.arc.queries.QueryContext
+import io.cratis.arc.queries.QueryRequest
+import io.cratis.arc.queries.QueryValidator
+import io.cratis.arc.results.ValidationResult
+import org.springframework.stereotype.Component
+
+@Component
+class TaskQueryValidator : QueryValidator {
+    override val queryName: FullyQualifiedQueryName? = null
+
+    override suspend fun validate(request: QueryRequest, context: QueryContext): List<ValidationResult> =
+        if (request.arguments["title"] == "") {
+            listOf(ValidationResult.error("A task title is required.", listOf("title")))
+        } else {
+            emptyList()
+        }
+}
+```
+
+This example rejects an explicitly empty title; add the absence rule separately
+when omission is invalid for the selected query.
+
 ### `ConceptValidator<TConcept>`
 
 A reusable invariant on a `ConceptAs<T>` concept type, walked automatically
@@ -251,7 +280,7 @@ fun billingCommandFilter(): CommandFilter = BillingCommandFilter()
 
 ## Order of execution
 
-Typed `CommandValidator`/`QueryValidator` rules run once, before the shared
+Typed `CommandValidator` and request-based `QueryValidator` rules run once, before the shared
 model/concept traversal. A separately registered `ModelValidator` for the
 command's own class is a distinct rule that also runs once at the root.
 Cancellation from any validator — a concept validator, a Kotlin property
@@ -264,6 +293,8 @@ exception result; it is not silently skipped.
 
 - Defining the command or query the rule attaches to:
   `cratis-arc-command-kotlin`, `cratis-arc-query-kotlin`.
+- In-process rule assertions and dependency pins: `cratis-arc-testing-kotlin`.
+- Authentication, identity and tenancy: `cratis-arc-identity-and-tenancy-kotlin`.
 - Append-time Chronicle uniqueness/concurrency: `cratis-chronicle-event-constraints`.
 - The C# Arc validation shape (`ConceptValidator<T>`, `CommandValidator<T>`,
   Provide short-circuiting): `cratis-arc-command-validation`.
@@ -283,3 +314,5 @@ exception result; it is not silently skipped.
   every rule expressed with `FluentModelValidator` — verify with a build that
   regenerates the proxy.
 - `./gradlew build` is clean with zero warnings and zero errors.
+- Exercise rejection through `cratis-arc-testing-kotlin`; `shouldBeInvalid()`
+  must prove a rule ran, not only a missing dependency.

package/package/corpus/skills/cratis-arc-validation-typescript/SKILL.md

@@ -20,14 +20,14 @@ generator copies into generated proxies. Setup is in
 
 ## Verified product sources
 
-Verified against `Cratis/Arc.TypeScript` `main` at commit `94d398d` (tag
-`v0.33.0` plus three commits), reading `Source/Core/validation/**` (including
+Verified against `Cratis/Arc.TypeScript` tag **v0.57.2** (GitHub pre-release;
+server packages 0.57.2, not on npm), reading `Source/Core/validation/**` (including
 `index.ts`, `ValidationResult.ts`, `Severity.ts`, `RuleBuilder.ts`),
 `Source/Core/commands/Outcome.ts`, `Documentation/commands/command-validation.md`,
 `validation-severity-filtering.md`, `command-outcomes.md`,
 `Documentation/queries/validation.md`, `Documentation/concepts.md`,
 `Documentation/proxy-generation/validation.md`, `Source/Testing`, and the
-`Samples/Tasks` validators. Rechecked against `main` at `3cc6ab3` (v0.34.0) for the result helpers.
+`Samples/Tasks` validators.
 `ValidationResult` is both the exported interface and a value with the helpers
 `ValidationResult.information/warning/error(message, options?)`; the positional
 `validation(...)` function remains available.
@@ -180,6 +180,8 @@ export class RenameTaskValidator extends CommandValidator<RenameTask> {
   your message.
 - It works **only** inside a validator of a model-bound command, during
   validation. Validators do not receive read models through their constructors.
+- Reads are scoped to the current command/tenant and cancellation signal, on
+  both validate and execute routes; do not retain a validation read across calls.
 
 ## Rule vocabulary
 

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

@@ -16,13 +16,19 @@ This skill is verified against these exact sources:
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Cli` | `3.2.0` | the `cratis` command, its contexts, output formats, and command tree |
+| `Cratis.Cli` | `3.53.1` | command effects, confirmations, contexts, output and command tree |
+| `Cratis.Chronicle` | `19.32.0` | the CLI's Chronicle client package |
+| `Cratis.Chronicle` | `19.50.1` | server authentication configuration and development-client registration |
 
-> Re-verified at `Cratis/cli` **v3.2.0** (originally written against 2.4.0): every command, branch, flag and output format this skill names exists there; the 2.x→3.x change is the Chronicle 17/18 wire migration plus new branches (`ai`, `arc`, `screenplay`, `prologue`, `llm`) this skill does not cover.
-| `Cratis.Chronicle` | `18.3.0` | the observer, partition, sequence, and job concepts the CLI reads |
+Re-verified at `Cratis/cli v3.53.1`: since 3.2.0, observer removal,
+partition-quarantine clearing, server-bound login and broader diagnose scope
+have changed operational guidance. Read [command effects](references/command-effects.md)
+when classifying a mutation or confirmation; it cites the exact tag.
 
 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:
+that catalog is the authority for exact command names, `effect` and
+`requiresConfirmation` on the installed version. Treat every effect other than
+`read-only` (including unknown values) as a state change:
 
 ```bash
 cratis llm-context          # every command, option and argument as JSON
@@ -66,8 +72,29 @@ The connection string resolves in this exact order:
 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.
+no embedded `user:pass@` and no `apiKey=` (embedded credentials win): use a cached
+login token only for its issuing server and while valid (more than one minute
+before expiry), then context client id/secret, then the built-in development
+client. The CLI does not restrict that fallback to localhost; acceptance depends
+on the server's authentication configuration and registered clients, not its
+address. Development builds can register that client automatically; do not rely
+on a remote server rejecting it. An expired matching login without
+client credentials raises `LoginSessionExpired` (exit 4), not a silent fallback.
+A login belonging to another server is not sent; a once-per-process stderr
+notice explains the mismatch.
+
+Use `cratis chronicle login <user>` (`--secret` or prompt), `chronicle logout`
+and `chronicle auth status -o json` (`tokenServer`, `loginMatchesServer`). Login
+refuses multi-host and `chronicle+srv://` targets. CLIs before 3.21.0 discarded
+the login token; log in again after upgrading. Context values can be changed
+with `context set-value server|event-store|namespace|client-id|client-secret`.
+Keep secrets out of logs and committed configuration.
+Evidence: [ChronicleSettings.cs](https://github.com/Cratis/cli/blob/v3.53.1/Source/Cli/Commands/Chronicle/ChronicleSettings.cs)
+and [authentication](https://github.com/Cratis/cli/blob/v3.53.1/Documentation/chronicle/auth.md).
+Server evidence at Chronicle v19.50.1:
+[authentication configuration](https://github.com/Cratis/Chronicle/blob/v19.50.1/Source/Kernel/Core/Configuration/Authentication.cs)
+and [development-client registration](https://github.com/Cratis/Chronicle/blob/v19.50.1/Source/Kernel/Core/Setup/Authentication/AuthenticationService.cs)
+(`EnsureDefaultClientCredentials`, compiled under `DEVELOPMENT`).
 
 Prefer a named context over repeating a connection string:
 
@@ -103,13 +130,15 @@ There is one output flag, `-o` / `--output`, with values `table`, `plain`,
 
 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.
+error; `6` is `changes_pending` for `render --check`, not Chronicle commands.
+JSON errors carry an `error` code such as `not_found`, `connection_error`,
+`server_error`, `authentication_error` or `validation_error`.
 
 ## Where to look
 
 | Question | Where to look |
 | --- | --- |
-| Is the server healthy at all? | `cratis chronicle diagnose` (exit code 3 when unhealthy) |
+| Is the server healthy at all? | `cratis chronicle diagnose`; `--all-namespaces`, `--all-event-stores`, `--watch --interval <seconds>`; non-zero for unhealthy, quarantined or incomplete checks |
 | 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>` (`events tail` returns only the highest sequence number — not a count, not the events) |
@@ -119,19 +148,26 @@ error.
 | 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`.
+Classify inspection through `effect=read-only` in `cratis llm-context`, not a
+remembered allowlist. `chronicle report-error` is cataloged read-only, but opens
+a browser issue form; the harness guard deliberately blocks that external UI
+action.
+
+`read-models get|snapshots|instances <READ_MODEL>` takes the **Identifier** column
+of `read-models list`, not the container name. `events get` accepts `--sequence`,
+`--from`, `--to`, `--event-source-id` and `--event-type` (comma-separated, optional
+`Type+gen`). It has no limit option: bound `--from`/`--to` and prefer `-o plain`.
+The catalog recommends plain for `event-types list`, `projections list` and
+`read-models instances`, and json-compact for `read-models get`.
 
 ## 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.
+- **A failed partition is not necessarily quarantined.** Eligible failures retry
+  automatically under the configured budget; quarantined partitions stop retrying.
+  Missing `IsQuarantined` is Unknown, not healthy. A stale value can mean lag or a
+  stopped partition: inspect attempts and observer state rather than guessing.
+  Observer clear does not clear partition quarantine. Source: Chronicle
+  **v19.50.1**, `Documentation/concepts/observers.mdx`.
 - **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.** A quarantine ends when
@@ -141,6 +177,12 @@ list|show`, `failed-partitions list|show`, `projections list|show`,
   not the first. A redeploy that restarts the client can also end the quarantine
   as a side effect, so check the observer's state before and after a redeploy.
 
+- **Observer and partition quarantine are separate.** `observers clear-quarantine`
+  clears only the observer. `observers clear-partition-quarantine <observer> <partition>`
+  needs Chronicle 19.29.0+, resets the retry budget and retries unless `--no-retry`
+  is given; handler side effects may repeat. `retry-partition` exits non-zero
+  when quarantined or not failed. `jobs resume` resumes Stopped jobs, not Failed.
+
 ## Before you change anything
 
 Default to read-only inspection. A request to diagnose a live store does not
@@ -150,12 +192,20 @@ These commands mutate the running store:
 
 - `chronicle observers replay`, `replay-partition`, `retry-partition`,
   `clear-quarantine`
+- `chronicle observers remove` — destructive across every namespace of the event
+  store: definition, state, handled counts, failures and projection definition;
+  read model data stays. Refused while running or subscribed, no force flag.
+- `chronicle observers clear-partition-quarantine` — may retry the handler
 - `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`
 
+This is the v3.53.1 surface, not the authority for later versions; check the
+catalog's `effect` before acting. `chronicle login/logout` are `local`, while
+`chronicle workbench` is `destructive` because its keys can mutate the store.
+
 Where the Cratis hooks are installed, this boundary is enforced: a `PreToolUse` guard on shell
 commands blocks every `cratis chronicle` command that is not on its read-only allowlist, unknown
 commands and the interactive `workbench` included, with or without `--yes`. When it blocks, do not
@@ -172,22 +222,24 @@ Before any of them:
 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.
+4. Show the intended change (and a dry run where supported) 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
 
 **Destructive commands fail closed outside a terminal.** Every command with a
 confirmation prompt — `observers replay`, `observers replay-partition`,
-`observers retry-partition`, `observers clear-quarantine`, `jobs stop`,
+`observers retry-partition`, `observers clear-quarantine`,
+`observers clear-partition-quarantine`, `observers remove`, `jobs stop`,
 `jobs resume`, `recommendations perform`, `recommendations ignore`,
 `users remove`, `applications remove`, `subscriptions remove` — asks
 interactively, and when the session is **not** interactive (a script, a
 pipeline, an agent harness) it does *not* proceed: it writes
 "Re-run the command with --yes to confirm the operation" and exits with the
 validation error code. `--yes` is therefore the only way a non-interactive run
-performs one of these, which makes `--yes` the authorization boundary. Declining
+performs one of these. It is confirmation, **not user authorization**; check
+`requiresConfirmation` independently from `effect` in the installed catalog. Declining
 the interactive prompt exits successfully having done nothing.
 
 **Additive commands do not prompt.** `users add`, `applications add` and
@@ -207,10 +259,12 @@ 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.
+- `cratis-chronicle-mcp-inspection` offers read-mostly inspection/design-time
+  tools and job control only; replay, retry and observer recovery are CLI work.
+- The terminal Workbench (`cratis chronicle workbench`) presents the same data
+  with mutating keys; a human at a terminal uses it, not an agent harness.
 - The browser Workbench owns redaction, revision, and event-type authoring.
+- Narrator (VS Code extension `cratis.narrator`, verified at `v3.0.2`) browses stores, event types, observers and projections from the editor, using the same contexts in `~/.cratis/config.json`.
 - 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.