Hub operations

The Hub is the operating console for Unphish itself. It is where Engram and Unphish operators run the platform: track environment health, manage internal team, configure provider secrets, and watch deployment readiness.

You will only see Hub if your system_role is staff or admin. Customer admins and partner operators do not see Hub; they have their own surfaces.

What the Hub looks like

Section	Purpose
Environments	Tiles for Demo, Staging, Production, Workbench. Each shows readiness, data source state, latest deployment, and pending blockers.
Team	Internal Unphish team membership: invitations, roles, expiry, removal, audit.
Secrets	Provider credential metadata (Vercel/Render env mapping, fingerprints, last-check status). Raw secrets are not stored or displayed.
Readiness	Per-environment readiness checklist: Authentik, database, providers, workers, storage, queue.
Activity	Hub-relevant events: deployments, secret rotations, invite flows, impersonation starts.
Delivery board	Internal Kanban for ongoing platform work.
Architecture	Live system diagram and links to canonical specs in /docs/.

Daily / weekly Hub tasks

Watch readiness

The first thing to check is /hub/readiness. Each environment shows green / amber / red across:

• Database — Postgres connectivity, pool health, recent migration status.
• Authentik — OIDC discovery reachable, admin token valid, recent auth failures within tolerance.
• Providers — per-provider mode (live / fixture / sandbox / unconfigured) and last health-check result.
• Workers — Render Temporal worker heartbeat, task-queue lag, recent retries / DLQ counts.
• Storage — S3 / Vercel Blob reachable, recent upload success, evidence storage path resolution.

Anything not green has a remediation link. Resolve before promoting deployments.

Manage internal team

/hub/team is for Unphish-internal team members: Engram developers, Unphish staff analysts, Unphish admin operators. Invitation flow is identical to the dashboard team flow but scoped to the platform organization. Internal-domain emails (@unphish.com, @engram.org) auto-promote organization admin / owner to system_role: admin. Partner and client admins do not auto-promote.

Use Hub team to manage:

• Invitations (create, resend, revoke, expire).
• Role assignment (owner, admin, analyst, viewer).
• Capability overlays (e.g., enforcement.submit_live, delivery_board.manage, architecture.manage).
• Removal and audit.

Manage provider secrets

/hub/secrets is the operator surface for credentials. The app database stores only metadata: provider, key name, target environment, masked fingerprint, last-check timestamp, last-check status, audit history.

To rotate a credential:

1. Update the value in Vercel environment variables (for app-runtime providers) or Render env groups (for worker-runtime providers), scoped to the appropriate environment (preview / staging / production).
2. Redeploy the affected service so the new env value is loaded.
3. Trigger a Hub re-check (/hub/secrets/[id]/recheck). The new fingerprint should appear; status should flip to green.
4. The old fingerprint is preserved in audit history.

The Hub does not know the secret value and never displays it. If you need to inspect the actual secret, you do that in Vercel/Render with the appropriate access controls.

Watch deployment activity

/hub/activity aggregates platform-relevant events:

• Deployments (Vercel previews and production promotions).
• Authentik configuration changes (especially secret_rotate events that require admin token updates).
• Provider mode flips (fixture → live is a notable event).
• Impersonation starts and stops.
• High-volume migration runs.

Cross-reference with the Delivery board to map events to in-flight work.

Promote a release

Production promotion is gated by:

1. CI must pass — lint, typecheck, build, dump audit (where applicable).
2. Preview QA must be signed off — the relevant QA checklist for the surface area.
3. Migration report must be approved if the release includes a migration.
4. Rollback documented — the deployment annotation includes the rollback procedure.

Promotion happens in Vercel with the appropriate environment selection. Hub does not perform the promotion itself; it tracks the state.

Configure environments

Each environment tile (/hub/environments/[env]) shows:

• Hostname and DNS state.
• Authentik config — issuer, client ID, redirect URI, recovery URL, admin token fingerprint.
• Provider modes for the environment.
• Database connection — database name or branch, pool size, recent error rate.
• Worker queue — Temporal namespace, task queue, worker heartbeat, recent failures.

Environments are configured by editing the appropriate .env files / Vercel env vars / Render env groups; Hub does not write secrets directly. Hub reads the resulting state and surfaces it for operators.

What Hub deliberately does not do

• Hub is not a customer surface. Customers and partners do not see it.
• Hub does not show fake roles. v1 had a role slider for previewing other personas. v2 replaces that with explicit support preview, which is capability-gated and audited.
• Hub does not store secrets. It stores metadata and fingerprints. Secret values live in Vercel / Render.
• Hub does not bypass readiness. If readiness is red, you cannot promote. Override requires explicit capability and is audited.

When something is broken

Use this rough triage:

Symptom	First place to look
Customers cannot sign in	/hub/readiness → Authentik tile
Provider calls failing for one provider	/hub/secrets → that provider's last-check status
Provider calls failing across the board	/hub/readiness → worker heartbeat and queue lag
Customer reports missing data	/hub/readiness → database tile, then /admin/audit for the affected tenant
Deployment looks stuck	/hub/activity → latest deploy event; cross-reference Vercel dashboard
Migration looks wrong	/admin/imports for the affected run; check the validation report

If the symptom is wider than one section, escalate via the Delivery board with the affected environment, time, and observed impact.