box/CLIENT-ONBOARDING-RUNBOOK.md

# Client Onboarding & Fleet Runbook (`CLIENT-ONBOARDING-RUNBOOK.md`)

## 1. Overview & Agency Context
This document defines the complete standard operating procedure (SOP) and automated runbook for provisioning, authenticating, and onboarding client agency profiles (nodes) into the NetVM multi-tenant fleet on `bl`.

In accordance with the NetVM Ethics Charter (`https://start.muse-dev.online/ethics.html`):
- Managed services are strictly run for consenting clients with explicit authority.
- Every client receives a completely isolated network namespace (`warp-<node>`), dedicated WireGuard tunnel identity, isolated Chrome profile, and separate credentials.
- Canonical Naming Convention: `node == agent == profile == API account`.

---

## 2. Fleet Architecture & Port Allocation

The fleet uses a deterministic `94x0` CDP port and `warp-<node>` naming convention:

| Node | CDP Port | Netns | Egress IP | Purpose / Profile |
|------|----------|-------|-----------|-------------------|
| `muse` | `9410` | `warp-muse` | Dedicated WARP | Primary Dev / Orchestrator |
| `pip` | `9420` | `warp-pip` | Dedicated WARP | Production Agent |
| `646` | `9430` | `warp-646` | Dedicated WARP | Production Agent |
| `opm` | `9440` | `warp-opm` | Dedicated WARP | Production Agent |
| `def` | `9450` | `warp-def` | Dedicated WARP | Production Agent |
| `<new>` | `9460+` | `warp-<new>`| Dedicated WARP | Next provisioned client node |

---

## 3. Step-by-Step Client Onboarding SOP

### Phase 1: Infrastructure Provisioning (Automated)
Run the idempotent node provisioning script to generate the WireGuard identity, network namespace, CDP relay, and chrome-box profile:

```bash
# Example: Provisioning node 'dev1'
./bin/netvm-provision-node.sh dev1
```
*Verification:*
- Namespace created: `ip netns list | grep warp-dev1`
- Registry updated in `NODES.md` and `ACCOUNTS.md`.

---

### Phase 2: Sign-in Initiation (`super cred initiate`)
Launch the client login flow without handling raw passwords or secrets:

```bash
# For email OTP login:
super cred initiate --node dev1 --email client@domain.com

# Or via Python Agent API:
python3 bin/cred-client.py initiate --node dev1 --email client@domain.com
```

- If already authenticated, exits `0` (`active`).
- If awaiting verification code, exits `2` (`awaiting_otp`).

---

### Phase 3: Submitting Transient OTP (`super cred submit-otp`)
When the client or operator receives the 6-digit email OTP:

```bash
super cred submit-otp --node dev1 --otp 123456
```

- The code is submitted transiently and is never persisted to disk or logs.
- If the account directly enters chat, status transitions to `active`.
- If the account requires age verification, it advances to Phase 4.

---

### Phase 4: Resolving the Age Verification Gate (`/access/verification`)
When a brand-new or unlinked client profile reaches the Muse age verification gate:

#### Method A: Instagram Linking (Recommended)
1. Run:
   ```bash
   super cred link-instagram --node dev1 [--notify]
   ```
2. The system provides a one-tap Tailscale portal URL:
   `http://bl.tailfb5960.ts.net:8765/verify/dev1`
3. **Crucial Rule**: The operator or client must link an **established / aged Instagram profile** (not created within minutes). Brand-new Instagram accounts lack mature age signals, causing Meta Accounts Center to disable the Confirm button.
4. If completed via mobile/desktop browser, use an Incognito/Private window to prevent ambient Meta cookie bleed.
5. If executing automated RPA in-browser, inject the Instagram credentials and security code directly into the container's CDP session.

#### Method B: Credit Card Verification (Fallback)
If Instagram linking is not available, operator can complete the verification using a client payment card on `/access/verification`.

---

### Phase 4.1: Edge Gate — Hard Audience Lockout (`/access` vs `/access/verification`)
- **Observed Behavior**: If an account routes to `https://muse.ai/access` with the text `"Muse isn't available to all audiences."` instead of `https://muse.ai/access/verification`:
  - The Meta account is temporarily unverified or lacks linked identity signals.
  - The in-app endpoint (`/api/hatch/age-confirmation/linking-web-auth`) returns `403 Forbidden`.
  - Reloading or navigating directly to `/` or `/access/verification` immediately redirects back to `/access`.
- **Root Cause**:
  - Meta accounts without an active linked profile (Facebook or Instagram) trigger Meta's general audience filter on Muse before the conversational AI product can be initialized.
  - In addition, attempting automated sign-in on low-reputation / unverified identities directly from server/VPN IPs will trigger Google reCAPTCHA Enterprise checkpoints (`auth_platform/recaptcha`).
- **Proven Unblocking SOP (The Direct Meta Accounts Center Flow)**:
  1. Open a clean browser session with the target Meta Account signed in (`https://accountscenter.meta.com/`).
  2. Navigate to **Accounts** → **Add Accounts** (`/add_accounts/`).
  3. Enter the Instagram credentials for an older/established IG profile (`veryraremeta`, `paradahub`, etc.) and submit any required 2FA/email OTP.
  4. If returned to Accounts Center, click **Add Instagram** again to initiate the OAuth handoff:
     `https://www.instagram.com/fxcal/auth/login/?app_id=633385687760560...&flow=igcalcomet&entry_point=frl_web_settings`
  5. On the *"Meta needs to access info from your Instagram account"* prompt, click **[Continue]**.
  6. Accounts Center returns to the confirmation screen (`/add/?auth_flow=ig_linking&token=...&blob=...`) → click **[Confirm]**.
  7. Meta sends security confirmation: *"Did you just move your profiles into the same Meta Account?"*.
  8. Once confirmed in Accounts Center, simply navigate back or reload `https://muse.ai/` inside the NetVM node. The `/access` lockout drops immediately, and the node enters active chat (*"Hey! I'm your personal agent..."*).

### Phase 4.2: Automated CDP Meta Linking Bot
When an edge-gate is detected or when linking a fresh client profile:
1. Trigger the automated CDP driver:
   ```bash
   sudo ip netns exec warp-<node> python3 /home/super/Projects/NetVM/bin/meta-acct.py link-instagram <node>
   ```
2. The bot:
   - Navigates headless Chromium to `https://accountscenter.meta.com/manage/`.
   - Locates and clicks **Add profiles and devices**.
   - Selects the Instagram cross-app linking flow.
   - Automatically navigates to the `frl_web_settings` FXCAL OAuth grant.
3. Once completed or after submitting Instagram credentials, re-query the account state:
   ```bash
   super cred meta-audit --node <node>
   ```

---

### Phase 5: Vitality & Status Monitoring
Query individual or fleet-wide health:

```bash
# Check single node
super cred status --node dev1

# Check entire fleet
super cred list
```

---

## 4. Rate-Limiting & Operational Safety Rules

To avoid platform anti-automation challenges and maintain high reputation:
1. **Pacing / Spacing**: Space new node creations and Instagram authorizations by **at least 15–20 minutes** per IP/session.
2. **Namespace Isolation**: Never attempt multi-account auth inside the same browser profile. Always execute inside the client's dedicated `warp-<node>` netns.
3. **No Credential Logging**: Never print plain text passwords or authentication tokens to stdout, git-tracked markdown, or plain text logs.