helix-forge/wiki/OpsHubBootstrapRunbook.md

Ops Hub Bootstrap Runbook

Date: 2026-05-16

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.

Inputs

• Manifest draft: wiki/ops-hub-manifest.draft.json
• Widget seed: wiki/ops-hub-widgets.seed.json
• Migration fallback: wiki/ops-hub-bootstrap.sql

Current Bootstrap Decision

Use the authenticated Inter-Hub admin UI first. Use the SQL migration fallback only when a repeatable deployment-side bootstrap is needed before the v2 API is hardened.

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

• hub_family: vsm
• vsm_function: OPS
• vsm_system: S1

Inter-Hub does not yet have first-class hub metadata columns for these values.

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.

Validation

After manifest activation:

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:

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:

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.