mypa

MyPA Skill

MyPA is a voice-first personal communication hub. Every message is a Tez (short for Tezit) — a discrete, actionable item with its full context iceberg preserved forever. This skill lets you send messages to teammates, manage your tez feed, get briefings, interrogate context, and share mirrors.

Quick Start for External OpenClaw

This skill works with any OpenClaw runtime, not just the MyPA Canvas UI.

1. Install

cp SKILL.md ~/.openclaw/workspace/skills/mypa/SKILL.md

2. Set Environment

export MYPA_API_URL="https://api.mypa.chat"   # or your instance URL
export MYPA_EMAIL="[email protected]"
export MYPA_PASSWORD="your-password"
# Optional: for PA-to-PA messaging
export RELAY_URL="https://relay.tezit.com"     # or your relay URL

3. Verify

# Login
TOKEN=$(curl -s -X POST "$MYPA_API_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"$MYPA_EMAIL\",\"password\":\"$MYPA_PASSWORD\"}" | jq -r '.data.tokens.accessToken')

# Bootstrap — discover teams, capabilities, endpoints
curl -s "$MYPA_API_URL/api/auth/bootstrap" -H "Authorization: Bearer $TOKEN" | jq .

If you see data.user and data.teams in the response, you're connected.

Bootstrap Flow (CRITICAL for External Runtimes)

On first contact with a MyPA instance, always run the bootstrap sequence:

1. Login → POST /api/auth/login → store accessToken + refreshToken
2. Bootstrap → GET /api/auth/bootstrap → discover:
   • teams[] — all teams the user belongs to
   • capabilities — which integrations are available (relay, crm, paWorkspace, federation, scheduler)
   • instanceMode — "team" or "personal"
   • connectedHubs — (personal mode only) federated team hubs
   • endpoints — backend URL, relay URL, cross-team URL
3. If teams.length > 1 → present the list and ask the user which team to scope to
4. If teams.length === 1 → set scope automatically
5. Store the resolved team scope in conversation memory for subsequent operations

curl "$MYPA_API_URL/api/auth/bootstrap" \
  -H "Authorization: Bearer $TOKEN"

Response shape:

{
  "data": {
    "user": { "id": "uuid", "email": "...", "name": "...", "department": "...", "teamId": "uuid" },
    "teams": [{ "id": "uuid", "name": "Alpha Team", "role": "member", "isActive": true, "memberCount": 4 }],
    "instanceMode": "team",
    "capabilities": { "relay": true, "crm": false, "paWorkspace": false, "federation": true, "scheduler": false },
    "connectedHubs": [],
    "endpoints": { "backend": "https://api.mypa.chat", "relay": "http://10.108.0.2:3002", "crossTeam": null }
  }
}

Multi-Team Scope Resolution (CRITICAL)

Users may belong to multiple teams. Write operations must be scoped to a specific team.

Rules

• Read operations (context, briefing, feed, library search): use the user's active team by default. In personal mode, can aggregate across all teams.
• Write operations (create team card, classify, relay share): MUST have an explicit teamId when the user belongs to 2+ teams.
• Disambiguation protocol: if teams.length > 1 and no teamId is specified, the backend returns AMBIGUOUS_TEAM_SCOPE with the list of teams. Present this to the user and ask them to choose.

Handling AMBIGUOUS_TEAM_SCOPE

If a write operation returns HTTP 400 with error.code === "AMBIGUOUS_TEAM_SCOPE":

{
  "error": {
    "code": "AMBIGUOUS_TEAM_SCOPE",
    "message": "User is a member of multiple teams. Specify teamId explicitly.",
    "teams": [
      { "id": "team-1-uuid", "name": "Alpha Team", "role": "member" },
      { "id": "team-2-uuid", "name": "Beta Team", "role": "admin" }
    ]
  }
}

Agent response: Present the team list and ask the user which team they mean. Then retry the operation with the selected teamId.

Scope Modes

• team:{teamId} — scoped to a specific team (default for write operations)
• personal — local data only (user's personal tezits, no team context)
• all-teams — read-only aggregation across all connected teams (personal instance mode only, via cross-team endpoints)

Authentication

All requests require a JWT Bearer token. Obtain one by logging in.

Login:

curl -X POST "$MYPA_API_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "'"$MYPA_EMAIL"'", "password": "'"$MYPA_PASSWORD"'"}'

Store accessToken and refreshToken from the response. Include on every request:

Authorization: Bearer $TOKEN

Access tokens expire after 15 minutes. On 401, refresh:

curl -X POST "$MYPA_API_URL/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "'"$REFRESH_TOKEN"'"}'

Optional CRM Environment

If Twenty CRM is configured for this deployment, set:

export TWENTY_API_URL="http://localhost:3000"
export TWENTY_API_KEY="your_twenty_api_key"

Use CRM calls only when both are present. If missing, continue with MyPA-only workflows.

Optional PA Workspace bridge for Google execution flows:

export PA_WORKSPACE_API_URL="http://localhost:3003"

When set, CRM orchestration can optionally execute PA email/calendar actions in addition to Tez draft generation.

CRM + Tez Operations

IMPORTANT: Before any CRM operation, check CRM status first. If configured: true and reachable: true, proceed with CRM calls. If not, inform the user that CRM is not yet set up.

CRM Intent Routing (CRITICAL)

Treat CRM as an API integration (Twenty), not a local workspace file.

When a user asks things like:

• "add this person to CRM"
• "update that deal"
• "show my contacts/opportunities/tasks"

You MUST:

1. Call GET /api/crm/status first.
2. If data.configured === true and data.reachable === true, execute CRM API calls (/api/crm/people, /api/crm/opportunities, /api/crm/tasks).
3. If not configured/reachable, tell the user CRM integration is not configured or unreachable and ask for setup help (URL/key), not for a file path.

You MUST NOT:

• ask the user for a "CRM file", "CRM folder", or local CRM path as the primary approach.
• claim CRM is unavailable just because no local file exists.

Example user request:

"Add my wife, Natalie Williams to our CRM."

Expected action flow:

1. GET /api/crm/status
2. If healthy, POST /api/crm/people with structured name:

curl -X POST "$MYPA_API_URL/api/crm/people" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"name":{"firstName":"Natalie","lastName":"Williams"}}}'

3. Confirm creation result to user.

Check CRM + runtime status

curl "$MYPA_API_URL/api/crm/status" \
  -H "Authorization: Bearer $TOKEN"

curl "$MYPA_API_URL/api/crm/workflows/status" \
  -H "Authorization: Bearer $TOKEN"

List CRM entities

curl "$MYPA_API_URL/api/crm/people?limit=20" \
  -H "Authorization: Bearer $TOKEN"

curl "$MYPA_API_URL/api/crm/opportunities?limit=20" \
  -H "Authorization: Bearer $TOKEN"

curl "$MYPA_API_URL/api/crm/tasks?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Write CRM entities (create/update)

Create a person — name is a structured {firstName, lastName} object. Use emails.primaryEmail for email.

curl -X POST "$MYPA_API_URL/api/crm/people" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"name":{"firstName":"Jane","lastName":"Example"},"emails":{"primaryEmail":"[email protected]"},"jobTitle":"VP Sales","city":"New York","phones":{"primaryPhoneNumber":"+15551234567"}}}'

Update a person — PATCH with only the fields to change:

curl -X PATCH "$MYPA_API_URL/api/crm/people/<entity-id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"jobTitle":"CTO","city":"San Francisco"}}'

Update a task:

curl -X PATCH "$MYPA_API_URL/api/crm/tasks/<task-id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"status":"in_progress"}}'

Build Tez-ready context from CRM

curl -X POST "$MYPA_API_URL/api/crm/tez-context" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entityType":"opportunity","entityId":"<id>"}'

Use data.relayContext with relay /tez/share or /conversations/:id/messages.

Cross-system coordination workflow

curl -X POST "$MYPA_API_URL/api/crm/workflows/coordinate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType":"opportunity",
    "entityId":"<id>",
    "objective":"Move deal to next stage with clear owner actions",
    "tez":{"teamId":"<team-id>","recipients":["<user-id>"]},
    "openclaw":{"enabled":true},
    "googleWorkspace":{"enabled":true,"dryRun":true}
  }'

This returns:

• tezDraft (ready for relay /tez/share)
• openclaw planning summary
• googleWorkspace draft/execute result (dry-run by default)

Key Concepts

Tez-Based Model: Everything is a tez. Tezits are discrete, actionable items — not threads.

Personal vs Team Tezits:

• "Message for Me" → personal tez (private note, reminder). Only the creator sees it.
• "Message for Team" → team tez sent to specific recipients or all team members.

Library of Context: ALL original content (voice transcripts, typed text) is preserved forever. Context is sacred — never suggest deleting it.

Status State Machine:

pending → active → resolved → archived

archived is terminal. Transitions are enforced by the API.

Sending Messages (CRITICAL)

Step 0: Resolve Team Scope

Before any write operation, ensure you have a resolved team scope:

• If user is in 1 team → scope is set automatically (no teamId needed)
• If user is in 2+ teams → you MUST include teamId in write reques

---

Content truncated.