PopKit Cloud Signup

Create a new PopKit Cloud account and obtain an API key for enhanced semantic intelligence features.

When to Use

• User runs

  /popkit:cloud signup

• User wants to enable cloud enhancements (semantic routing, pattern learning)
• User needs to create an account to access cloud features

Input

User provides (via AskUserQuestion):

• Email address
• Password (minimum 8 characters)

Optional flags:

• --skip-test

  : Skip connection testing after signup

Process

1. Check for Existing Configuration

Before starting signup, check if user already has cloud config:

from pathlib import Path
import json
import os

config_path = Path.home() / ".claude/popkit/cloud-config.json"

# Check config file
if config_path.exists():
    with open(config_path) as f:
        config = json.load(f)
        email = config.get("email")

    print(f"⚠️  Existing cloud config found for {email}")

    # Use AskUserQuestion to confirm
    # question: "You already have a cloud account. What would you like to do?"
    # options:
    #   1. "Continue with new signup" (will overwrite existing)
    #   2. "Login to existing account" (invoke pop-cloud-login skill)
    #   3. "Cancel"

# Check environment variable
if os.environ.get("POPKIT_API_KEY"):
    print("⚠️  POPKIT_API_KEY environment variable is already set")
    # Continue with signup but note it will be overridden

2. Collect User Credentials

Use AskUserQuestion for email, then custom text input for password:

Email Collection:

Use AskUserQuestion tool with:
- question: "What email would you like to use for your PopKit Cloud account?"
- header: "Email"
- options:
  1. label: "Enter email", description: "Type your email address"
- multiSelect: false

After user selects "Enter email", they'll be prompted for custom input.

Password Collection:

Use AskUserQuestion tool with:
- question: "Create a password for your account (minimum 8 characters)"
- header: "Password"
- options:
  1. label: "Enter password", description: "Type your password (will be hidden)"
- multiSelect: false

Validation:

• Email: Must contain @ and valid domain
• Password: Minimum 8 characters, no maximum

3. Create Account via Cloud API

Send signup request to PopKit Cloud:

import requests
import json

# Signup endpoint
url = "https://api.thehouseofdeals.com/v1/auth/signup"

# Request payload
payload = {
    "email": email,
    "password": password
}

# Send request
try:
    response = requests.post(url, json=payload, timeout=10)

    if response.status_code == 201:
        # Success
        data = response.json()
        api_key = data["api_key"]
        user_id = data["user_id"]
        tier = data.get("tier", "free")

        print(f"✅ Account created successfully")
        print(f"User ID: {user_id}")
        print(f"Tier: {tier}")

    elif response.status_code == 409:
        # Email already registered
        print("❌ Signup failed: Email already registered")
        print("\nTry logging in instead:")
        print("  /popkit:cloud login")
        return

    elif response.status_code == 400:
        # Validation error
        error = response.json().get("error", "Invalid input")
        print(f"❌ Signup failed: {error}")
        return

    else:
        # Other error
        print(f"❌ Signup failed: HTTP {response.status_code}")
        print(f"Error: {response.text}")
        return

except requests.exceptions.Timeout:
    print("❌ Signup failed: Request timed out")
    print("Check your internet connection and try again")
    return

except requests.exceptions.ConnectionError:
    print("❌ Signup failed: Could not connect to PopKit Cloud")
    print("Check your internet connection and try again")
    return

except Exception as e:
    print(f"❌ Signup failed: {e}")
    return

4. Save API Key Locally

Store API key securely in local config file:

from pathlib import Path
import json
import os

# Config directory
config_dir = Path.home() / ".claude/popkit"
config_dir.mkdir(parents=True, exist_ok=True)

# Config file
config_path = config_dir / "cloud-config.json"

# Prepare config
config = {
    "api_key": api_key,
    "email": email,
    "user_id": user_id,
    "tier": tier,
    "created_at": "2025-12-26T00:00:00Z"  # Use current timestamp
}

# Save config
with open(config_path, "w") as f:
    json.dump(config, f, indent=2)

# Set restrictive permissions (Unix/Mac only)
try:
    os.chmod(config_path, 0o600)
    print(f"🔒 API key saved securely: {config_path}")
except Exception:
    # Windows doesn't support chmod the same way
    print(f"✅ API key saved: {config_path}")

5. Test Connection

Verify the API key works by querying cloud status:

import requests

# Use cloud_client.py from power-mode
# (packages/popkit-core/power-mode/cloud_client.py)

try:
    headers = {"Authorization": f"Bearer {api_key}"}
    response = requests.get(
        "https://api.thehouseofdeals.com/v1/health",
        headers=headers,
        timeout=5
    )

    if response.status_code == 200:
        data = response.json()
        latency_ms = response.elapsed.total_seconds() * 1000

        print(f"✅ Cloud connection verified ({latency_ms:.0f}ms)")

    else:
        print(f"⚠️  Warning: Could not verify connection (HTTP {response.status_code})")
        print("Your account was created, but there may be a connection issue")

except Exception as e:
    print(f"⚠️  Warning: Could not test connection: {e}")
    print("Your account was created successfully")

6. Display Setup Instructions

Show user how to use their new API key:

✅ PopKit Cloud Account Created

**Email:** user@example.com
**API Key:** pk_live_abc123def456... (last 6 chars shown)
**Tier:** Free (100 requests/day)
**Config:** ~/.claude/popkit/cloud-config.json

---

## Quick Start

### Option 1: Use config file (recommended)

Your API key is already saved in `~/.claude/popkit/cloud-config.json`.
PopKit will automatically use it for cloud enhancements.

**Verify connection:**

```bash
/popkit:cloud status
```

Option 2: Set environment variable

For maximum portability, export the API key:

# Add to ~/.bashrc or ~/.zshrc
export POPKIT_API_KEY="pk_live_abc123def456..."

Then restart your shell or run:

source ~/.bashrc  # or ~/.zshrc

---

What's Enhanced?

With your API key configured, PopKit now has:

Core Workflows (Always Available)

✅ All development commands and skills work without API key

Cloud Enhancements (Now Active)

✅ Semantic agent routing - Better agent selection via embeddings ✅ Community pattern learning - Learn from other developers' solutions ✅ Cloud knowledge base - Access shared documentation and patterns ✅ Cross-project insights - Recommendations based on similar projects

---

Usage Limits

Free Tier:

• 100 API requests/day
• Unlimited local execution
• All workflows available

Need more? Upgrade at:

/popkit:upgrade

---

Next Steps

1. Verify connection:

   /popkit:cloud status
   

2. Test semantic routing:

   /popkit:next  # Uses embeddings to recommend next action
   

3. View account info:

   /popkit:account
   

---

Security Notes

• API key stored with chmod 600 (user read/write only)
• Password never stored locally
• All requests use HTTPS
• Config file:

  ~/.claude/popkit/cloud-config.json

To disconnect:

/popkit:cloud logout

### 7. Handle Errors

Common error scenarios:

**Email Already Registered (409):**
```markdown
❌ Signup Failed

**Error:** Email already registered

This email is already associated with a PopKit Cloud account.

Try logging in instead:
```bash
/popkit:cloud login

Or use a different email address.

**Invalid Email/Password (400):**
```markdown
❌ Signup Failed

**Error:** Invalid email or password

Requirements:
- Email: Must be valid format (contains @ and domain)
- Password: Minimum 8 characters

Please try again with valid credentials.

Connection Timeout:

❌ Signup Failed

**Error:** Request timed out

Could not connect to PopKit Cloud within 10 seconds.

Please check:

1. Your internet connection
2. Firewall/proxy settings
3. Cloud status: https://status.thehouseofdeals.com

Try again in a moment.

Unknown Error:

❌ Signup Failed

**Error:** {error_message}

If this persists, please:

1. Report the issue: `/popkit:bug report`
2. Check cloud status: https://status.thehouseofdeals.com
3. Contact support: joseph@thehouseofdeals.com

Output

Success Case

✅ PopKit Cloud Account Created

**Email:** user@example.com
**API Key:** **\*\***def456 (saved securely)
**Tier:** Free (100 requests/day)

### Quick Start

1. **Verify connection:**
   ```bash
   /popkit:cloud status
   ```

2. Cloud enhancements now active:
   • Semantic agent routing ✅
   • Community pattern learning ✅
   • Cloud knowledge base ✅
   • Cross-project insights ✅

Config file: ~/.claude/popkit/cloud-config.json

Run

/popkit:account

for detailed account info.

### Failure Case

```markdown
❌ Signup Failed

**Error:** Email already registered

Try logging in instead:
```bash
/popkit:cloud login

## Related Skills

- `pop-cloud-login` - Login to existing account
- `pop-cloud-status` - Check connection status
- `pop-cloud-logout` - Disconnect from cloud

## Security

**API Key Storage:**
- File: `~/.claude/popkit/cloud-config.json`
- Permissions: chmod 600 (user read/write only)
- Never logged in full (only last 6 chars shown)

**Password Handling:**
- Never stored locally
- Only transmitted to cloud API over HTTPS
- Never logged or printed

**Best Practices:**
- Use strong passwords (16+ characters recommended)
- Don't share API keys
- Use `/popkit:cloud logout` when switching accounts