docs: adopt the Krateo Documentation Standard

.github/workflows/lint.yaml

@@ -13,6 +13,11 @@ permissions:
   contents: read
 
 jobs:
+  # Krateo Documentation Standard conformance (shared org workflow): the invariant
+  # docs/ file set, frontmatter, link integrity, banned dead-org strings, examples
+  # pairing.
+  lint-docs:
+    uses: krateo-platformops/.github/.github/workflows/lint-docs.yaml@main
   lint:
     runs-on: ubuntu-latest
     steps:

README.md

@@ -1,41 +1,70 @@
-# krateo-clickstack-chart
+# clickstack-chart
 
-Krateo PlatformOps **observability** blueprint repo. Groups the ClickStack wrapper with the
-collectors and event proxy that feed and surface it. All charts publish to the consolidated
-registry `oci://ghcr.io/krateo-platformops/charts`.
+The deployment unit for Krateo's observability stack: four Helm charts — the ClickStack
+wrapper, two OpenTelemetry collectors, the SSE proxy — published to
+`oci://ghcr.io/krateo-platformops/charts` and turned into Krateo compositions by the
+[installer](https://github.com/krateo-platformops/installer).
 
-Part of the [krateo-installer](https://github.com/krateo-platformops/installer) ecosystem.
+## What is this
 
-## Charts
+A chart repo, not a code repo: it wraps the upstream ClickStack chart (ClickHouse + OTel
+gateway + HyperDX + MongoDB) and the upstream `opentelemetry-collector` chart, folds in the
+Krateo glue (the `/events` handler, the composition-id enrichment wiring, the portal-bell
+SSE proxy), and ships a `values.schema.json` per chart so `core-provider` can generate typed
+composition CRDs. The collector and sse-proxy **code** lives in
+`krateo-platformops/otel-collector` and `krateo-platformops/sse-proxy`.
+Full picture: [docs/index.md](docs/index.md).
 
-| Path | Chart | OCI artifact | Purpose |
-|------|-------|--------------|---------|
-| `charts/krateo-observability` | `krateo-observability` | `oci://ghcr.io/krateo-platformops/charts/observability` | ClickStack (ClickHouse + OTel gateway + HyperDX + MongoDB) wrapper: `values.schema.json`, the ClickHouse http-handlers ConfigMap, the otel-clickhouse credentials Secret and a HyperDX LoadBalancer Service. The composition the installer uses (Kind `KrateoObservability`) |
-| `charts/otel-collector-deployment` | `otel-collector-deployment` | `oci://ghcr.io/krateo-platformops/charts/otel-collector-deployment` | Cluster-level OTel collector that enriches K8s events with `krateo.io/composition-id` and exports to ClickHouse |
-| `charts/otel-collector-daemonset` | `otel-collector-daemonset` | `oci://ghcr.io/krateo-platformops/charts/otel-collector-daemonset` | Node-level OTel collector for pod logs, host and kubelet metrics |
-| `charts/krateo-sse-proxy` | `krateo-sse-proxy` | `oci://ghcr.io/krateo-platformops/charts/sse-proxy` | Polls ClickHouse and pushes new K8s events to the portal via Server-Sent Events |
+## Install
 
-## How the installer consumes it
-
-The installer umbrella emits a `CompositionDefinition` per chart, pointing `core-provider` at the
-OCI artifacts above; `core-provider` generates the typed CRDs and reconciles one Composition per
-instance. The collectors depend on the `krateo-observability` composition (for the ClickHouse
-credentials Secret), and `krateo-sse-proxy` is exposed so the portal's events bell can reach it.
-
-## Local validation
+Normally installed by the **Krateo installer** (portal feature, `tier: observability`).
+Standalone, in dependency order (wrapper first — it creates the credentials Secret the
+collectors mount; ClickHouse + MongoDB operators must already be installed):
 
 ```sh
-helm lint charts/krateo-observability
-helm template smoke charts/krateo-observability
+helm install krateo-observability oci://ghcr.io/krateo-platformops/charts/krateo-observability \
+  --version 0.1.11 --namespace krateo-system --create-namespace
+helm install otel-collector-deployment oci://ghcr.io/krateo-platformops/charts/otel-collector-deployment \
+  --version 0.3.3 --namespace krateo-system
+helm install otel-collector-daemonset oci://ghcr.io/krateo-platformops/charts/otel-collector-daemonset \
+  --version 0.1.5 --namespace krateo-system
+helm install krateo-sse-proxy oci://ghcr.io/krateo-platformops/charts/krateo-sse-proxy \
+  --version 0.1.6 --namespace krateo-system
 ```
 
-## Release
+Details and the composition path: [docs/usage.md](docs/usage.md).
+
+## Configure
+
+See [docs/configuration.md](docs/configuration.md). Most used:
+
+| Setting | Default | Effect |
+|---|---|---|
+| `global.storageClassName` (wrapper) | `standard-rwo` | StorageClass for ClickHouse/Keeper/Mongo volumes (GKE default; override off-GKE). |
+| `hyperdxLoadBalancer.enabled` (wrapper) | `true` | The extra LoadBalancer Service exposing the HyperDX UI on `:3000`. |
+| `clickstack.clickhouse.cluster.spec.*` (wrapper) | 8Gi limit / 15Gi volume | The ONLY path upstream honours for ClickHouse resources/storage — top-level `clickhouse.*` keys are inert. |
+
+## Examples
 
-Push a semver tag (`X.Y.Z`) — CI packages every chart under `charts/*` at its declared version
-and publishes to `oci://ghcr.io/krateo-platformops/charts`. Charts that still carry the `CHART_VERSION`
-placeholder (e.g. `clickstack`) track the tag; independently-pinned charts keep their own version.
+- [examples/observability-composition](examples/observability-composition) — deploy the
+  ClickStack wrapper as a Krateo composition (CompositionDefinition + a `KrateoObservability` CR).
 
-## Links
+## Docs
+
+- [docs/index.md](docs/index.md) — the map (bundle + the `ops/` reference corpus)
+- [docs/overview.md](docs/overview.md) — what the four charts deploy and how
+- [docs/usage.md](docs/usage.md) — installer path, standalone install, local validation
+- [docs/configuration.md](docs/configuration.md) — the whole per-chart values surface
+- [docs/api.md](docs/api.md) — generated composition types, HTTP surfaces, upstream CRs
+- [docs/examples.md](docs/examples.md) — examples index
+- [docs/release.md](docs/release.md) — how a release ships
+- [docs/log.md](docs/log.md) — curated history
+
+## Develop & release
+
+```sh
+for d in charts/*/; do helm dependency build "$d"; helm lint "$d"; helm template smoke "$d" >/dev/null; done
+```
 
-- Installer umbrella: https://github.com/krateo-platformops/installer
-- ClickStack: https://github.com/ClickHouse/ClickStack-helm-charts
+Push a plain-semver tag (`X.Y.Z`, no `v`) — CI publishes every chart at its own
+literally-pinned `Chart.yaml` version. Runbook: [docs/release.md](docs/release.md).

compositiondefinition.yaml

@@ -8,5 +8,5 @@ metadata:
   namespace: krateo-system
 spec:
   chart:
-    url: oci://ghcr.io/krateo-platformops/charts/observability
-    version: "0.1.8"
+    url: oci://ghcr.io/krateo-platformops/charts/krateo-observability
+    version: "0.1.11"

docs/api.md

@@ -0,0 +1,90 @@
+---
+type: API
+title: clickstack-chart — api
+description: The contract — the four generated composition types and their CompositionDefinitions, the HTTP surfaces (/events, SSE, HyperDX API, OTLP), and the upstream CRs the charts deploy but do not own.
+resource: oci://ghcr.io/krateo-platformops/charts/krateo-observability
+tags: [api, compositiondefinition, crd, clickhouse]
+timestamp: 2026-08-07T00:00:00Z
+---
+
+# API
+
+## No hand-authored CRDs
+
+**This repo ships NO CRD of its own.** There is no `crds-subchart/`, and none of its own
+templates render a `CustomResourceDefinition` — only ConfigMaps, Secrets, Services,
+Deployments and RBAC. The typed surface it exposes to the platform is **generated**:
+`core-provider` reads each chart's `values.schema.json` and derives a composition CRD, so
+the contract is edited by changing the chart values surface, never by editing CRD YAML.
+
+## The generated composition types
+
+The installer registers each chart as a composition (`tier: observability`, portal-gated):
+
+| Kind | Chart | OCI artifact |
+|------|-------|--------------|
+| `KrateoObservability` | `charts/krateo-observability` | `oci://ghcr.io/krateo-platformops/charts/krateo-observability` |
+| `OtelCollectorDeployment` | `charts/otel-collector-deployment` | `oci://ghcr.io/krateo-platformops/charts/otel-collector-deployment` |
+| `OtelCollectorDaemonset` | `charts/otel-collector-daemonset` | `oci://ghcr.io/krateo-platformops/charts/otel-collector-daemonset` |
+| `KrateoSseProxy` | `charts/krateo-sse-proxy` | `oci://ghcr.io/krateo-platformops/charts/krateo-sse-proxy` |
+
+All live in API group `composition.krateo.io`; the served version is derived from the
+pinned chart version (`0.1.11` → `v0-1-11`), so **a chart-version bump changes the CR's
+apiVersion**. The CR `spec` is the chart's values (typed by `values.schema.json`). The
+deployed version is always readable from the cluster:
+`CompositionDefinition.spec.chart.version`.
+
+The repo-root [`compositiondefinition.yaml`](../compositiondefinition.yaml) registers the
+wrapper standalone (`core.krateo.io/v1alpha1`, name `krateo-observability`, namespace
+`krateo-system`); in a real install the installer umbrella owns this and the per-collector
+CompositionDefinitions.
+
+## HTTP surfaces the deployed stack exposes
+
+- **`GET /events?composition_id=<uid>`** on ClickHouse HTTP (port 8123, via
+  `krateo-clickstack-clickhouse-clickhouse-headless`): a `predefined_query_handler`
+  declared in the wrapper's `cluster.spec.settings.extraConfig.http_handlers`. Returns the
+  latest 50 K8s events for a composition UID as JSON (name/namespace/uid/kind, reason,
+  message, type, eventTime, source_component) from `otel_logs` rows where
+  `telemetry.source = 'k8s-events'`. This is the ONLY supported event-query path — the
+  catch-all `/` dynamic-query handler exists to preserve ClickHouse's native API, not for
+  portal consumers. `/ping`, `/replicas_status` and `/metrics` are re-declared alongside it.
+- **The sse-proxy** (ClusterIP `:8080`, exposed by the installer for the browser): serves
+  the portal bell — the historical events snapshot and the `/notifications` SSE stream —
+  plus `/health` probes. Its in-cluster address is published as the fixed-name
+  **`sse-proxy-internal-endpoint` Secret** (`server-url`, `insecure: "true"`), which
+  snowplow RESTActions reference by exact name. The endpoint/stream contract is owned by the
+  code repo `krateo-platformops/sse-proxy`.
+- **HyperDX**: the UI at the `krateo-clickstack-app-lb` LoadBalancer (`:3000`) and the
+  Bearer-authenticated external API (`/api/v2/{alerts,webhooks,dashboards,sources}`,
+  HyperDX ≥ 2.28) at the **`krateo-clickstack-api`** ClusterIP (`:8000`) — the direct
+  backend port, because the port-3000 proxy strips `/api` and 404s the v2 routes.
+- **OTLP ingest**: the daemonset collector's `otlp` receiver (`:4317` grpc / `:4318` http),
+  reachable at the headless Service `otel-collector-daemonset-opentelemetry-collector.<ns>.svc`
+  under the installer — the endpoint platform components export traces/metrics to.
+
+## CRs it deploys but does NOT own
+
+The wrapper's heavy lifting is done through upstream operators' CRs, owned by those
+operators' CRDs:
+
+- **`ClickHouseCluster`** and **`KeeperCluster`** (the clickhouse.com operator) — rendered by
+  the vendored `clickstack` subchart, configured here only through
+  `clickstack.clickhouse.cluster.spec`. The operator (and its CRDs) must already be
+  installed; this repo neither ships nor versions them. Remember: upstream renders ONLY
+  `cluster.spec` — top-level `clickhouse.*` keys are inert
+  ([configuration](./configuration.md)).
+- **`MongoDBCommunity`** (the MongoDB community operator) — rendered by the subchart;
+  `spec.statefulSet.spec` passes through, which is how the chart sets the PVC retention
+  policy.
+- The two `otel-collector-*` charts render standard workloads + collector config from the
+  upstream `opentelemetry-collector` chart — no Krateo-owned CRD.
+
+## Where the real schemas live
+
+- **Composition types:** each chart's `values.schema.json` in THIS repo, read at the chart
+  tag.
+- **`ClickHouseCluster` / `MongoDBCommunity`:** the upstream operators.
+- **Runtime contracts** (the `compositionresolver` label semantics, the SSE stream shape):
+  the code repos `krateo-platformops/otel-collector` and `krateo-platformops/sse-proxy`, at
+  the image tags the charts pin.