# Workflows

Detailed step-by-step guides for multi-tool operations. Each step shows the tool
name and expected payload. Every org-scoped tool takes `organizationId`; account-level
tools do not. Argument names are exact — the live `tools/list` is the source of truth.

---

## 1. Project Lifecycle

The most common workflow. Creates and activates a monitoring project.

### Step 1: Verify Identity

```
get_current_user
```

Confirm authentication works. Note your user ID and name.

### Step 2: Select Organization

```
list_user_organizations
```

Pick the org where the project will live. Note its `id`.

If no org exists:

```
create_organization { name: "My Company" }
```

(`slug` is optional — generated from `name` if omitted.)

### Step 3: Create Project

```
create_project {
  organizationId: "<org_id>",
  name: "Fintech competitor watch",
  monitoringIntent: "Track pricing and feature changes from Stripe, Adyen, and Mollie. Flag anything affecting our SMB tier.",
  businessContext: "EU-based B2B payments platform serving SMBs. Compete on price and onboarding speed.",
  description: "Optional short label."
}
```

Returns the project with a generated ID. Initial status: `draft`.

**Required fields**: `organizationId`, `name`, `monitoringIntent`.
`businessContext` and `description` are optional. `monitoringIntent` describes
what to watch and is used at intake to generate monitoring topics.

### Step 4: Activate

```
update_project { organizationId: "<org_id>", id: "<project_id>", status: "active" }
```

Status changes from `draft` to `active`; monitoring runs on a weekly cadence.
Pause anytime with `status: "paused"`, and resume with `status: "active"`.

### Step 5: Inspect / Remove

```
get_project_by_id { organizationId: "<org_id>", id: "<project_id>" }
list_user_projects { organizationId: "<org_id>", offset: 0, limit: 20 }
delete_project    { organizationId: "<org_id>", id: "<project_id>" }
```

---

## 2. Team Management

### Step 1: Create Organization

```
create_organization { name: "Acme Corp" }
```

You become the `owner` automatically.

### Step 2: Invite Members

```
create_organization_invites {
  organizationId: "<org_id>",
  emails: ["alice@acme.com", "bob@acme.com"],
  role: "member"
}
```

Invitations are sent by email; invitees must accept to join. `role` applies to
all emails in the batch — send separate calls to assign different roles.
Invitees accept via `accept_organization_invite { token: "<invite_token>" }`
(an account-level tool the invited user runs).

### Step 3: Monitor Invites

```
list_organization_invites { organizationId: "<org_id>" }
```

Resend if needed:

```
resend_organization_invite { organizationId: "<org_id>", memberId: "<member_id>" }
```

Revoke if needed:

```
delete_organization_invite { organizationId: "<org_id>", memberId: "<member_id>" }
```

### Step 4: Manage Members & Roles

```
list_organization_members      { organizationId: "<org_id>" }
update_organization_member_role { organizationId: "<org_id>", memberId: "<member_id>", role: "admin" }
remove_organization_member      { organizationId: "<org_id>", memberId: "<member_id>" }
```

Roles: `owner` (1 per org, not reassignable via API), `admin`, `member`. Seats
are pre-purchased — you can only have as many members as your subscription's
seat count allows (hard ceiling 100/org).

### Step 5: Enforce Security

```
update_organization_security_settings {
  organizationId: "<org_id>",
  requireMfa: true
}
```

For MFA-specific settings including a grace period:

```
update_organization_mfa_settings {
  organizationId: "<org_id>",
  requireMfa: true,
  gracePeriodDays: 7
}
```

### Step 6: Configure SSO (optional)

```
update_organization_sso_config {
  organizationId: "<org_id>",
  provider: "okta",
  issuerUrl: "https://your-org.okta.com",
  clientId: "<client_id>",
  clientSecret: "<client_secret>"
}
```

Always test after configuring:

```
test_organization_sso_config { organizationId: "<org_id>" }
```

---

## 3. Billing, Subscriptions & Credits

### Subscribe to a Plan

```
create_checkout_session {
  organizationId: "<org_id>",
  tierId: "<plan_tier_id>",
  interval: "monthly",
  seatCount: 5,
  successUrl: "https://www.snooplytics.com/billing/success",
  cancelUrl: "https://www.snooplytics.com/billing/cancel"
}
```

Returns a Stripe Checkout URL. **The user must complete payment in their
browser.** The agent cannot process payment directly. `slotPacks` is optional.

### Verify Payment

After the user completes checkout:

```
verify_checkout_session { organizationId: "<org_id>", sessionId: "<cs_session_id>" }
```

Webhooks may lag — always verify rather than assuming success.

### Check Subscription & Usage

```
get_current_subscription { organizationId: "<org_id>" }
get_subscription_usage   { organizationId: "<org_id>" }
```

### Purchase a Credit Pack

```
create_credits_checkout_session {
  organizationId: "<org_id>",
  packId: "credits_100",
  successUrl: "https://www.snooplytics.com/billing/success",
  cancelUrl: "https://www.snooplytics.com/billing/cancel"
}
```

Pack IDs: `credits_25`, `credits_100`, `credits_500`. Same flow: returns URL →
user pays → `verify_checkout_session`. Credits are org-level; top-up credits
persist across the monthly base reset.

### Change or Cancel the Plan

`update_subscription` is set-to-value — pass the target state:

```
update_subscription { organizationId: "<org_id>", seatCount: 10 }
```

Or hand the user Stripe's hosted management page:

```
create_billing_portal_session { organizationId: "<org_id>" }
```

---

## 4. Domain Verification

### Add Domain

```
add_organization_domain { organizationId: "<org_id>", domain: "acme.com" }
```

Returns DNS records to configure.

### Verify After DNS Propagation

Allow time for DNS propagation, then:

```
verify_organization_domain { organizationId: "<org_id>", domainId: "<domain_id>" }
```

### List / Inspect / Remove

```
list_organization_domains  { organizationId: "<org_id>" }
get_organization_domain    { organizationId: "<org_id>", domainId: "<domain_id>" }
remove_organization_domain { organizationId: "<org_id>", domainId: "<domain_id>" }
```

---

## 5. Audit & Compliance

### Query Audit Logs

```
get_organization_audit_logs {
  organizationId: "<org_id>",
  offset: 0,
  limit: 50
}
```

Optional filters: `action`, `resourceType`, `resourceId`, `userId`,
`startDate`, `endDate`.

### Export as CSV

```
export_organization_audit_logs { organizationId: "<org_id>" }
```

---

## 6. API Key Management

### Create a Key

```
create_api_key { name: "CI Pipeline", scopes: ["projects:read", "projects:write"] }
```

`expiresIn` (seconds) and `metadata` are optional. **Save the token
immediately** — it cannot be retrieved after creation. The token starts with
`tkn_` and is used on the REST API via the `x-api-key` header.

### List and Manage

```
list_api_keys
get_api_key    { id: "<key_id>" }
update_api_key { id: "<key_id>", name: "Updated name" }
delete_api_key { id: "<key_id>" }
```