# 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:

```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.