docs: prepare ops-hub bootstrap handoff

2026-05-16 04:06:38 +02:00
parent 481c7a648e
commit 8ea7099b52
5 changed files with 579 additions and 6 deletions
--- a/wiki/OpsHubBootstrapRunbook.md
+++ b/wiki/OpsHubBootstrapRunbook.md
@@ -0,0 +1,108 @@
+# 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.