6.tSetup cartridge: operator-facing wizard for foundation configuration

1. Why a Setup cartridge

The current setup loop for a single foundation concern:

1. Operator reads the relevant Step doc (6.p for SSO, 6.n for OAuth, etc.).
2. Runs terraform output -raw <output-name> for the values the outside admin needs.
3. Drafts a Slack message or email with the values + the prereq checklist.
4. Outside admin replies with their return values (metadata URL, client_id, etc.).
5. Operator edits tfvars or Secrets Manager with the return values.
6. Runs terraform apply.
7. Verifies the configuration is live.

This works. It also has six problems:

• Discoverability. The operator has to know which Step doc covers which setup. Doctrine docs are organized by engineering topic, not by operator workflow.
• Copy-paste fragility. Hand-crafting Slack messages with output values risks typos and skipped prereq sections.
• State opacity. "Have we sent the SSO handoff to the Azure admin yet?" requires asking. No system of record for the in-flight state.
• Repeated work. Setting up Salesforce Sandbox + Salesforce Production is the same flow twice; we manually duplicate.
• Onboarding. A new platform operator has to read every Step doc to know what setups exist and which are pending.
• Distributed verification. "Is SSO live?" requires checking Cognito, Azure admin status, and the obs Cartridges tab. No single status surface.

The Setup cartridge addresses all six by giving operators a single, navigable list of foundation setups, each with its current state, the values to hand off, the inputs to capture, and the verification step. Same pattern GitBook uses for setup-heavy products.

2. Flows it covers

v1 ships the flows we already have doctrine for. Each flow has a wizard with stages.

Future flows (when their doctrine lands):

• GitHub OAuth provider registration
• GitBook OAuth provider registration
• Monday OAuth provider registration
• New cartridge approval (gating new cartridge deployments)
• Model router endpoint registration

3. Flow state machine

Each flow goes through stages. The cartridge tracks state in DDB so the operator opens the cartridge and immediately sees where every flow is.

Each transition is logged. The operator gets a stage badge per flow: green when verified, amber for in-flight, gray for not-started. The cartridge home page is a list of flows with their stage badges.

4. The copy-out / paste-back pattern

The single most important UX element. Modeled on how operators actually use the doctrine today (manually copying outputs into Slack).

Copy-out (handoff to outside admin)

Each handoff has:

• A formatted message template with the values pre-filled.
• A "Copy as Slack" button (formatted with backtick code blocks).
• A "Copy as email" button (formatted as a polite email).
• A "Download as Word" button for prereqs (the Howto.docx pattern we already used for Salesforce).
• A "Mark as sent" button that flips the flow to handoff-sent.

┌────────────────────────────────────────────────────────────────┐
│ Send to Azure admin                                            │
│                                                                │
│ Subject: PayCargo Forge SAML configuration                     │
│                                                                │
│ Hi,                                                            │
│                                                                │
│ Please configure the PayCargo Forge enterprise application in  │
│ Azure with the following SAML service provider details:        │
│                                                                │
│   ACS URL:    https://ai-sandbox-obs-app-95922820.auth         │
│               .us-east-1.amazoncognito.com/saml2/idpresponse   │
│   Entity ID: urn:amazon:cognito:sp:us-east-1_fJLnhjqnl         │
│                                                                │
│ The full prereq checklist (scopes, conditional access policy,  │
│ etc.) is attached.                                             │
│                                                                │
│ Please return: SAML metadata URL                               │
│                                                                │
│ Thanks,                                                        │
│ Mike Tang                                                      │
│                                                                │
│   [Copy as Slack]  [Copy as email]  [Download Howto.docx]      │
│   [Mark as sent]                                               │
└────────────────────────────────────────────────────────────────┘

Paste-back (capture return values)

Each return value is a labeled input field with:

• Inline validation (URL format, JSON shape, etc.).
• A description ("the federation metadata XML URL from the enterprise application").
• A "Test" button where applicable (e.g., for SAML metadata: fetch the URL and validate the XML).
• A submit button that writes to the right backend (SSM for non-secret config, Secrets Manager for secrets, generates a tfvars snippet for cases where Terraform is the source of truth).

┌────────────────────────────────────────────────────────────────┐
│ Capture Azure admin's response                                 │
│                                                                │
│ SAML metadata URL:                                             │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ https://login.microsoftonline.com/.../federationmetadata/. │ │
│ └────────────────────────────────────────────────────────────┘ │
│   [Test fetch]   (fetches the URL, validates XML, parses Entity)│
│                                                                │
│ Conditional access MFA on the app:  ○ Confirmed  ● Not yet     │
│                                                                │
│   [Save inputs]   (writes to SSM, generates Terraform snippet) │
└────────────────────────────────────────────────────────────────┘

5. Audience and auth

System admins only. Cognito group admins. Same gate as the obs Admin tab.

Federated SSO users without admin group cannot see this cartridge in the Console launcher (it doesn't appear on their tile grid). Direct URL access returns 403 from the cartridge backend.

The Setup cartridge is the system admin's operating surface. Doctrine 8.8 says system admins are Cognito-native; the Setup cartridge runs under that authority. SSO users do not configure the platform; they request access to it via the Request Roles cartridge.

6. Relationship to the CMS

The instructions inside each wizard (the "what the outside admin needs to do" text) are content. They belong in the CMS (Step 6.s) when CMS lands.

Until then, instructions ship as files inside the Setup cartridge code (similar to how the chatbot ships its system prompt). Each flow has a markdown file with the prereq narrative; the cartridge renders it as the wizard's middle pane.

When CMS lands (per Step 6.s):

• The Setup cartridge becomes a thin frame (forms + state).
• The instructional content is CMS-served (per-document versioning).
• Operators editing the prereq narrative use the CMS editor; the Setup cartridge picks up the new version on next load.
• The "Mark as sent" event in the Setup cartridge can capture WHICH version of the prereq content was sent, so the audit log is complete.

7. Relationship to tfvars + apply

Three patterns for where return values land. Each flow picks one.

The Setup cartridge knows which pattern each flow uses and surfaces the right UX. For SSM and Secrets Manager patterns, "Save inputs" writes immediately. For the tfvars pattern, "Save inputs" generates a copy-pasteable snippet and a "Open PR with this change" link to GitHub.

The SSO case

SSO uses Pattern 1 (SSM). After Azure admin returns the metadata URL:

1. Operator pastes URL into the Setup cartridge form.
2. Cartridge writes /forge/sso/azure-metadata-url in SSM.
3. Cartridge writes /forge/sso/enabled = true in SSM.
4. Operator clicks "Apply Terraform" in the cartridge.
5. Cartridge triggers the existing Terraform Apply workflow via GitHub workflow_dispatch (same way operators do today).
6. Terraform reads SSM at plan time, flips sso_enabled = true, applies the IdP resource.
7. Cartridge polls Cognito to verify the IdP exists; flips flow state to provisioned.
8. Operator clicks "Verify"; cartridge does a SAML test sign-in; flips to verified.

8. Architecture

Standard cartridge shape. API Gateway HTTP API + Lambda + DDB + CloudFront-fronted S3 frontend.

cartridges/global/setup/
  backend.tf                        Lambda + API Gateway + IAM
  frontend.tf                       S3 + CloudFront
  auth.tf                           Cognito client (admin group required)
  cartridge.tf                      Manifest

  lambda/
    handler.js                      Routes for each flow
    flows/
      sso.js                        SSO flow handler (state machine)
      dns.js                        DNS flow handler
      salesforce.js                 Salesforce setup flow handler
      ...
    state.js                        DDB state read/write

  frontend/
    index.html                      Cartridge home (flow list)
    setup-sso.html                  SSO wizard
    setup-dns.html                  DNS wizard
    setup-salesforce.html           Salesforce wizard
    js/
      wizard.js                     Shared wizard component (uses SDK Modal + Table)
      copy-out.js                   Copy-out card behavior
      paste-back.js                 Paste-back form behavior

  content/                          (until CMS lands)
    sso-prereqs.md                  Step 6.p section 12 in markdown
    dns-instructions.md             DNS admin instructions
    salesforce-howto.md             Salesforce Connected App walkthrough

DDB schema

Table: forge-setup-state

  pk: "flow"
  sk: flow_id           // e.g. "sso-azure", "dns-paycargo-org",
                        //      "salesforce-sandbox", "salesforce-production"

  Attributes:
    status:             // "not-started" | "inputs-displayed" | "handoff-sent" |
                        //   "inputs-captured" | "provisioned" | "verified"
    handoff_sent_by:    // cognito username
    handoff_sent_at:    // ISO timestamp
    inputs_captured_by: // cognito username
    inputs_captured_at: // ISO timestamp
    inputs:             // JSON map of return values (non-secret)
    provisioned_at:     // ISO timestamp (when TF apply succeeded)
    verified_at:        // ISO timestamp
    last_check_status:  // "ok" | "failed" | "pending"

9. Decisions to confirm

10. Ship plan

1. PR 1: this doc + Doctrine 2.11. Decisions locked. No code. New doctrine entry: "Operator setup is a cartridge flow, not a tfvars edit."
2. PR 2: cartridge skeleton. cartridges/global/setup/ with backend (Lambda + API Gateway + DDB + IAM), frontend (S3 + CloudFront), Cognito admin gate, manifest. Empty flow list (no flows implemented yet).
3. PR 3: shared wizard frontend components. wizard.js, copy-out.js, paste-back.js. Built on SDK v1 components. Generic enough to be reused per flow.
4. PR 4: SSO flow (first concrete flow). flows/sso.js, setup-sso.html, content/sso-prereqs.md. Updates console/sso.tf to read from SSM data sources instead of input variables. End-to-end test: operator clicks through, writes SSM, triggers apply, verifies.
5. PR 5: DNS flow. flows/dns.js + content. Reads from the domains module outputs; surfaces the 3 batches of records.
6. PR 6: Salesforce Sandbox flow. Includes Howto.docx generation, callback URL handoff, Consumer Key + Secret capture, write to Secrets Manager.
7. PR 7: add Setup tile to Console launcher. Visible only to admin group.

v1 ships after PR 7. Subsequent flows (Salesforce Production, GitHub, GitBook, Monday, etc.) are individual PRs adding one flows/<name>.js + content file + frontend page each.

References

• Step 6.p — SSO doctrine. The SSO flow is the first concrete flow in this cartridge.
• Step 6.n — OAuth doctrine. Future flows for GitHub / GitBook / Monday land here.
• Step 6.s — CMS doctrine. Setup cartridge instructions migrate to CMS once it ships.
• Doctrine — New entry 2.11 lands with PR 1: "Operator setup is a cartridge flow, not a tfvars edit."