# Connection Onboarding Workflow

**Status:** Approved target-state baseline  
**Technical seam:** I0/I1  
**Full UX:** I2.

## Target State

Connect external accounts/resources without breaking the user's current workflow.

```text
ConnectionRequirement detected
  -> offer eligible existing Connection(s)
  -> or Connect new
      authenticate / external redirect
      confirm identity/account
      discover resources/capabilities
      select least required resources/scope
      create/update Connection
      bind narrowly to Project
      verify health/capability
  -> satisfy requirement
  -> return to exact interrupted context
  -> re-evaluate blocked gate
  -> continue automatically
```

## Return Context

Before leaving for auth, persist:

```text
Project
PlanningSession / PlanRevision if applicable
active Decision / requirement
current draft/input
return route + active item
required capability/resource
```

Cancellation or failure returns to the same context without losing work.

## Existing Connection Reuse

If a suitable global Connection already exists, show identity/account/resources/capabilities and bind only required subset. Never silently grant a Project access merely because a user owns the Connection.

## Set Up Later

Allowed only when requirement is deferrable. Record owner, reason, consequence and exact `requiredByGate`. Readiness explains the later requirement; only that gate blocks.

## States / Errors

Distinguish authentication failure, insufficient permission, resource selection required, reauth/expiry, revoked, provider outage/degraded, adapter error and user cancellation. UX copy/actions match the category.

## Security

Raw tokens are entered only through trusted auth/secret flows and stored behind CredentialReference. After setup, UI shows identity/scope—not token value.

## Increment Realization

| Increment | Realization |
|---|---|
| I0/I1 | direct/manual Connection creation and scoped execution projection. |
| I2 | full in-context connect/defer/return UX. |
| I5/I6 | CI/deployment resources. |
| I9 | enterprise auth/org/provider connections. |

## Acceptance

A user can leave Planning for OAuth, select account/resource, return to exact Decision, and see the requirement satisfied without re-explaining context. Cancel and provider error preserve state.