docs(showcase): add dashboard update SOPs

Author: jpr5

showcase/README.md

@@ -154,3 +154,47 @@ Column ordering lives in `shell-dashboard/src/lib/sort-order.ts` — internal to
 - Dockerfile, `entrypoint.sh`, and build context (`shared_python/`, `shared_typescript/`) are shared between local and Railway.
 - `.github/workflows/showcase_deploy.yml` builds each image on push to `main` and pushes it to Railway. Per-PR deploys are opt-in via `gh workflow run showcase_deploy.yml -r <branch> -f service=<slug>`.
 - The only real differences at runtime are env var values and the URL. If something works locally in Docker, it works on Railway (and vice versa).
+
+## Updating the Dashboard
+
+The dashboard at [showcase.copilotkit.ai](https://showcase.copilotkit.ai) reads two data sources:
+
+1. **Static `catalog.json`** — generated at build time by `pnpm generate-registry`. Contains the full 38-feature x 17-integration cell matrix with status (`wired` / `stub` / `unshipped`), parity tiers, and feature categories. Changes require a generator run + commit.
+2. **Live PocketBase probe results** — streamed via SSE. Probes discover demo routes automatically and update the dashboard in real time. No manual intervention needed for probe data.
+
+Key invariants:
+
+- **Parity tiers are never manually set.** They are computed by comparing each integration's wired feature set against the reference integration's.
+- **The reference integration is auto-detected** as the integration with the most wired features (ties broken alphabetically). No `reference: true` flag exists.
+- **`catalog.json` is gitignored** — the generator emits it into the shell apps' `src/data/` directories, which are already in `.gitignore`.
+- **The `stub` status** means: feature declared in manifest, demo entry exists, but no `route` field. Today only `langgraph-python/cli-start` qualifies.
+
+### SOP 1: Wire a new demo on an existing integration
+
+1. Edit `showcase/packages/<slug>/manifest.yaml` — add the feature to `features[]` and a corresponding `demos[]` entry with a `route`.
+2. Run `pnpm generate-registry` — updates `registry.json` AND `catalog.json`. The cell flips from `unshipped` to `wired`. Parity tiers auto-recompute.
+3. Commit the manifest + both generated files. PR, merge.
+4. CI rebuilds the package image + dashboard image. Railway auto-deploys both.
+5. Ops probes discover the new demo route and begin probing. Dashboard updates live via PocketBase SSE — no further action needed.
+
+### SOP 2: Code fix on an existing demo (no manifest change)
+
+1. Edit code under `showcase/packages/<slug>/src/...`.
+2. PR, merge. No generator run needed (manifest unchanged).
+3. CI rebuilds the package image. Railway auto-deploys.
+4. Probes re-probe on the next tick. If the fix turns a red cell green, the dashboard updates live. Zero manual steps beyond the normal PR workflow.
+
+### SOP 3: Add a brand-new integration
+
+1. Create `showcase/packages/<new-slug>/manifest.yaml` with `features[]` + `demos[]`.
+2. Add `{"slug": "<new-slug>", "name": "<Display Name>"}` to `showcase/shared/packages.json`.
+3. Provision a Railway service (manual: `railway service create` or Dashboard UI).
+4. Run `pnpm generate-registry` — catalog gains 38 new cells (mostly `unshipped`, some `wired`). Parity tier computed automatically.
+5. Commit, PR, merge. CI + Railway deploy. Probes discover the new service automatically via the Railway discovery filter.
+
+### SOP 4: Reference migration (move the reference integration)
+
+1. No manual flag needed — the generator auto-detects the reference as the integration with the most wired features (ties broken alphabetically).
+2. If you want a *different* integration to be reference, wire more features on it until it leads the count.
+3. Run `pnpm generate-registry` — all parity tiers recompute automatically.
+4. Commit, PR, merge.