helix-forge/wiki/OpsHubBootstrapRunbook.md

# Ops Hub Bootstrap Runbook

Date: 2026-06-14

## Purpose

This runbook gives the operator-ready bootstrap path for `ops-hub`, the VSM
Operations / System 1 extension of Inter-Hub.

Use this when an authenticated Inter-Hub admin session or deployment migration
is available. The current public v2 API is not sufficient to create the hub,
manifest, API consumer, API key, or seed widgets by itself.

As of 2026-06-06, implementation work for `ops-hub` belongs in the dedicated
repo at `/home/worsch/ops-hub` with remote `gitea-remote:coulomb/ops-hub.git`.
This runbook remains a HelixForge bootstrap handoff reference until the
implementation repo ports or supersedes it.

## Inputs

- Manifest draft: `wiki/ops-hub-manifest.draft.json`
- Widget seed: `wiki/ops-hub-widgets.seed.json`
- Migration fallback: `wiki/ops-hub-bootstrap.sql`
- Implementation repo: `/home/worsch/ops-hub`

## Current Bootstrap Decision

Prefer the supported Inter-Hub bootstrap API once production exposes the
current API surface. Do not proceed with manual DB seeding unless the operator
explicitly chooses that fallback. Until the production API gate passes, the
authenticated Inter-Hub admin UI and SQL migration remain fallback paths for
attended operator use only.

Production API gate:

- `https://hub.coulomb.social/api/v2/hubs` returns `401` unauthenticated, not
  `404`.
- OpenAPI lists `/hubs`, `/hub-capability-manifests`, `/api-consumers`, and
  `/policy-scopes`.
- After the gate passes, run the supported bootstrap/smoke path from the
  relevant `inter-hub` or `ops-hub` tooling with `IHUB_BASE` and an operator
  key.

Latest check, 2026-06-14:

- `ops-hub/scripts/interhub-gate-probe.py` still reports the production gate
  closed.
- `GET /api/v2/hubs` returns `404`.
- Live OpenAPI still omits `/hubs`, `/hub-capability-manifests`,
  `/api-consumers`, and `/policy-scopes`.
- Do not run the preferred API bootstrap path until the current Inter-Hub API
  is deployed, unless the operator explicitly chooses the SQL fallback.

VSM classification is stored in the manifest capability description for now:

- `hub_family`: `vsm`
- `vsm_function`: `OPS`
- `vsm_system`: `S1`

Newer Inter-Hub schemas have first-class hub metadata columns for these values.
The SQL fallback sets those columns when present and still carries the same
classification in the manifest description for older deployments.

As of the 2026-05-19 access check, the workstation kubeconfig only points at
CoulombCore (`92.205.130.254`) and does not include the Railiance01
(`92.205.62.239`) cluster where `hub.coulomb.social` resolves. SSH key access
to `root`, `worsch`, and `ubuntu` on Railiance01 was denied, so the SQL fallback
must be run from a host/session that already has Railiance01 cluster access.

## UI Path

1. Log in to Inter-Hub at `https://hub.coulomb.social/NewSession`.
2. Open `/Hubs/new`.
3. Create the hub:
   - Name: `Ops Hub`
   - Slug: `ops-hub`
   - Domain: `ops.coulomb.social`
   - Kind: `domain`
4. Open `/HubCapabilityManifests/new?hubId=<ops-hub-id>`.
5. Create a draft manifest with:
   - Version: `1.0`
   - Capability description from `wiki/ops-hub-manifest.draft.json`
   - Contact: operator/team contact
6. Edit the manifest and copy in:
   - `declaredWidgetTypes`
   - `declaredEventTypes`
   - `declaredAnnotationCategories`
   - `declaredPolicyScopes`
7. Activate the manifest.
8. Open `/ApiConsumers/new`.
9. Create an API consumer bound to the active ops manifest:
   - Name: `ops-hub`
   - Description: `API consumer for the VSM Operations hub`
   - Scopes for the key: `framework:read hub:ops-hub:read hub:ops-hub:write`
10. Generate an API key and store it only in the operator secret store or local
    environment. Do not commit it to Git.
11. Seed the widgets from `wiki/ops-hub-widgets.seed.json` through the UI or
    migration fallback.

## SQL Fallback Path

From a shell with Railiance01 Kubernetes access, run:

```bash
kubectl exec -i -n databases net-kingdom-pg-1 -- \
  psql -U postgres -d interhub \
  < /home/worsch/helix-forge/wiki/ops-hub-bootstrap.sql
```

If using the HostEurope kubeconfig from the workstation, first restore
`~/.kube/config-hosteurope` as documented by `railiance-cluster`, then run:

```bash
KUBECONFIG=~/.kube/config-hosteurope \
kubectl exec -i -n databases net-kingdom-pg-1 -- \
  psql -U postgres -d interhub \
  < /home/worsch/helix-forge/wiki/ops-hub-bootstrap.sql
```

The SQL fallback creates the hub, active manifest, registry entries, API
consumer row, and seed widgets. It does not create the one-time visible static
API key; generate that in the authenticated Inter-Hub UI and store it outside
Git.

## Validation

After manifest activation:

```bash
curl -s https://hub.coulomb.social/api/v2/widget-types
curl -s https://hub.coulomb.social/api/v2/event-types
curl -s https://hub.coulomb.social/api/v2/annotation-categories
```

Expected: ops-owned vocabulary appears in the relevant registries.

After API key creation:

```bash
curl -s -X POST https://hub.coulomb.social/api/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<api-consumer-id>" \
  --data-urlencode "client_secret=<static-api-key>" \
  --data-urlencode "scope=framework:read hub:ops-hub:read hub:ops-hub:write"
```

Expected: a short-lived access token is returned.

After widget seeding:

```bash
curl -s https://hub.coulomb.social/api/v2/hub-registry
```

Expected: `ops-hub` is visible, and the operator can see the seeded widgets in
the authenticated UI.

## Known Blockers

- The live public v2 API has no `POST /api/v2/hubs`.
- The live public v2 API has no `POST /api/v2/widgets`.
- There are no v2 endpoints for manifest creation/activation.
- There are no v2 endpoints for API consumer or key creation.
- There is no `/api/v2/policy-scopes`.
- Interaction event create currently does not persist submitted metadata.
- Webhook dispatch currently uses the hard-coded `"clicked"` event type.

These are tracked by HF-WP-0001 T10 for Inter-Hub hardening.