Decision Ops Get Started Guide

This guide maps directly to the implemented Get Started flow in the Decision Ops dashboard at /onboarding.

Prerequisites

• API worker running on http://127.0.0.1:8787
• Dashboard dev server running on http://127.0.0.1:5173 (npm run dev:web)
• DASHBOARD_BASE_URL set to your dashboard origin before npm run env:sync (for local dev: http://127.0.0.1:5173)
• A valid org API key in browser storage:
  • easiest path: sign in at /login (GitHub or magic link) and let bootstrap configure it
  • alternative: create one from POST /v1/admin/api-keys and paste it in onboarding/settings
• Note: onboarding launcher snippets use demo-dashboard-token as an example placeholder; replace with your real token.

1. Dashboard First

Use this when you want the fastest hands-on validation path.

Steps:

1. Save the service token.
2. Run Run Policy Check.
3. Open Decisions, PR Checks, then Drift Trends.

2. GitHub First

Use this when PR governance is your first priority.

Steps:

1. Keep repo policy in advisory.
2. Run sample policy check to validate policy evaluation wiring.
3. Inspect burn-in recommendations on PR Checks.

3. Agent / MCP First

Use this when coding is mostly agent-driven.

Steps:

1. Generate repo hook instructions from Generate Hooks.
2. Add the output into AGENTS.md.
3. Use MCP launcher command to validate tool connectivity.

4. ADR Import First

Use this when you already have ADR/MADR history.

Steps:

1. Use the ingestion launcher command.
2. Validate imported decisions on Decisions.
3. Review observability on Drift Trends.

5. API First

Use this for platform automation and scripted rollout.

Steps:

1. Run the burn-in launcher command.
2. Promote repos only when readiness criteria are met.
3. Keep advisory by default until false positive targets are stable.

Readiness Checklist Meaning

The onboarding page readiness panel is live from GET /v1/admin/setup-status and checks:

• token configured
• accepted decisions available
• repo policy configured
• policy runs present
• drift points present
• MCP calls observed
• non-draft ADR versions imported

PR Flow Smoke Validation

Use this after GitHub App installation to validate the full webhook/check-run/policy pipeline:

npm run smoke:pr-flow -- --owner decisionops --repo decisionops-pr-flow-smoke

What it validates:

1. GitHub App is installed for the target repo (/v1/admin/github-app/validate-repo).
2. Advisory policy can be configured for that repo.
3. PR webhook is accepted by gatekeeper.
4. policy_runs increases via async jobs pipeline.
5. GitHub check-run is posted with completed DecisionRecord Policy Check.