Rewrite the README and fix inaccurate generated docs and workbench hints

.vscode/settings.json

@@ -58,12 +58,16 @@
         "Autofac",
         "automap",
         "Bevhavior",
+        "Bookshop",
         "Brotli",
         "Bson",
         "Buildx",
         "camelcase",
         "causations",
         "changesets",
+        "CLAUDECODE",
+        "compdef",
+        "compinit",
         "Cratis",
         "Cupertino",
         "datatable",
@@ -85,6 +89,7 @@
         "façade",
         "Finalizers",
         "fluentui",
+        "Forsgren",
         "Froms",
         "Gridlines",
         "Grpc",
@@ -97,6 +102,7 @@
         "Insurtech",
         "Intrinsics",
         "IPII",
+        "Kleppmann",
         "maxcpucount",
         "mermaidchart",
         "Meziantou",
@@ -107,12 +113,15 @@
         "Newtonsoft",
         "notnull",
         "nupkg",
+        "Nygard",
         "Offboarded",
         "Onboarded",
         "openiddict",
         "OTEL",
         "Otlp",
         "overlaypanel",
+        "palettegen",
+        "paletteuse",
         "PII",
         "Pkcs",
         "primeicons",
@@ -142,6 +151,7 @@
         "treetable",
         "tseslint",
         "tsyringe",
+        "ttyd",
         "typeparam",
         "typewind",
         "Unmap",

CHRONICLE.md

@@ -1,6 +1,6 @@
 # Chronicle CLI Reference
 
-Generated by `cratis init` (CLI v1.0.0.0). For the full machine-readable capability descriptor, run `cratis llm-context`.
+Generated by `cratis init` (CLI v1.0.0.0). Run `cratis init --refresh` to update.
 
 ## What is Chronicle?
 
@@ -13,73 +13,44 @@ The `cratis` CLI connects to a Chronicle server to inspect and manage event stor
 The CLI resolves the server connection in this order:
 1. `--server` flag
 2. `CHRONICLE_CONNECTION_STRING` environment variable
-3. Active context in `~/.cratis/config.json`
+3. Active context in `<home>/.cratis/config.json` — run `cratis context path` to see the resolved path on your system
 4. Default: `chronicle://localhost:35000`
 
 ```bash
-# Set up a named context
+# Create a named context
 cratis context create dev --server chronicle://localhost:35000
 cratis context set dev
 ```
 
-## Command Overview
-
-| Command Group | Key Commands |
-|---|---|
-| `event-stores` | list |
-| `namespaces` | list |
-| `event-types` | list, show |
-| `events` | get, count (tail), has |
-| `observers` | list, show, replay, replay-partition, retry-partition, clear-quarantine |
-| `failed-partitions` | list, show |
-| `recommendations` | list, perform, ignore |
-| `identities` | list |
-| `projections` | list, show |
-| `read-models` | list, instances, get, occurrences, snapshots |
-| `auth` | status, login, logout |
-| `users` | list, add, remove |
-| `applications` | list, add, remove, rotate-secret |
-| `context` | list, create, set, show, delete, rename |
-| `config` | show, set, path |
-| (top-level) | version, update, llm-context, init |
-
-## Global Flags
-
-| Flag | Description |
-|---|---|
-| `--server <CONNECTION_STRING>` | Chronicle server connection string |
-| `-o, --output <FORMAT>` | Output format: table (rich terminal), plain (tab-separated), json, json-compact |
-| `-q, --quiet` | Output only key identifiers, one per line |
-| `-y, --yes` | Skip confirmation prompts |
-| `-e, --event-store <NAME>` | Event store name (default: default) |
-| `-n, --namespace <NAME>` | Namespace (default: Default) |
-
 ## Output Format Guidance
 
-- Use `--output plain` for list commands (up to 34x fewer tokens than JSON).
+- Use `--output plain` for list commands that return large payloads — roughly 4-5x fewer tokens than `json`, and the gap widens with row count because JSON repeats every field name on every row.
 - Use `--output json-compact` when you need structured data with fewer tokens than `json`.
-- Use `--quiet` to get only IDs for piping: `cratis observers list -q | xargs -I {} cratis observers replay {} -y`
-- JSON errors include a machine-parseable `error` code alongside the `message`.
+- Use `--quiet` (`-q`) to get only IDs for piping: `cratis chronicle observers list -q | xargs -I {} cratis chronicle observers replay {} -y`
+- Use `--yes` (`-y`) to skip confirmation prompts in scripts and automation.
+- JSON errors include a machine-parseable `error` code alongside the human-readable `message` field.
 
 ## Troubleshooting Decision Tree
 
 ### Cannot connect to server
 1. Run `cratis version -o json` — check if server version appears.
-2. Check connection string: `cratis config show -o json`.
-3. Verify server is running and reachable on the configured port.
+2. Run `cratis chronicle diagnose -o json` — one round trip covering connectivity, observers, failed partitions and recommendations.
+3. Check the resolved connection: `cratis context show -o json`.
+4. Verify the server is running and reachable on the configured port.
 
 ### Observer stuck or behind
-1. Run `cratis observers list -o plain` — check observer state and sequence numbers.
-2. Run `cratis observers show <id> -o json` — inspect detailed state.
-3. Check failed partitions: `cratis failed-partitions list -o plain`.
-4. If a partition is failing, inspect: `cratis failed-partitions show <observer-id> <partition>`.
-5. Fix the underlying issue, then retry: `cratis observers retry-partition <observer-id> <partition> -y`.
-6. To replay from scratch: `cratis observers replay <observer-id> -y`.
+1. Run `cratis chronicle observers list -o plain` — check observer state and sequence numbers.
+   A `Next#` behind the log tail is not by itself a problem: an observer only advances over event types it subscribes to.
+2. Run `cratis chronicle observers show <id> -o json` — inspect detailed state.
+3. Check failed partitions: `cratis chronicle failed-partitions list -o plain`.
+4. If a partition is failing, inspect: `cratis chronicle failed-partitions show <observer-id> <partition>`.
+5. Fix the underlying issue, then retry: `cratis chronicle observers retry-partition <observer-id> <partition> -y`.
+6. To replay from scratch: `cratis chronicle observers replay <observer-id> -y`.
 
 ### Data not appearing in read model
-1. Verify events exist: `cratis events has <event-source-id>`.
-2. Check the projection observer is running: `cratis observers list --type projection -o plain`.
-3. Check read model instances: `cratis read-models instances <name>`.
+1. Verify events exist: `cratis chronicle events get --event-source-id <event-source-id> -o plain`.
+2. Check the projection observer is running: `cratis chronicle observers list --type projection -o plain`.
+3. Check read model instances: `cratis chronicle read-models instances <name>`.
 4. Check for failed partitions on the projection observer.
 
 ## Safety Notes
@@ -88,7 +59,10 @@ cratis context set dev
 - Use `--yes` only in automation with proper safeguards.
 - Remove commands (users, applications) are irreversible.
 
-## Further Reading
+## Command Reference
+
+The full command catalog is available as an AI skill — load it on demand when you need exact command names, options, or arguments:
 
-- Full machine-readable descriptor: `cratis llm-context`
-- CLI version and compatibility: `cratis version -o json`
+- **GitHub Copilot**: invoke the `chronicle-cli` skill
+- **Claude Code**: run the `/chronicle-cli` slash command
+- **Any tool**: run `cratis llm-context` for a live JSON dump, or `cratis llm-context --schema` for the JSON Schema