{
  "schemaVersion": "2026-04-10",
  "kind": "odei_agent_registration_contract",
  "name": "ODEI Agent Registration Contract",
  "canonicalOrigin": "https://api.odei.ai",
  "canonicalUrl": "https://api.odei.ai/.well-known/odei-agent-registration.json",
  "status": "active",
  "purpose": "Allow an external agent to guide or submit ODEI personal-runtime registration from any first-party ODEI asset without inventing a second onboarding backend.",
  "supportedAssistants": [
    {
      "handle": "claude",
      "assistantId": "claude-code",
      "label": "Claude Code"
    },
    {
      "handle": "codex",
      "assistantId": "codex",
      "label": "Codex"
    },
    {
      "handle": "gemini",
      "assistantId": "gemini",
      "label": "Gemini"
    },
    {
      "handle": "grok",
      "assistantId": "grok",
      "label": "Grok"
    }
  ],
  "entryAssets": [
    {
      "origin": "https://odei.ai",
      "role": "company_and_product_discovery"
    },
    {
      "origin": "https://api.odei.ai",
      "role": "canonical_api_and_registration_contract"
    },
    {
      "origin": "https://app.odei.ai",
      "role": "wallet_and_operator_onboarding_surface"
    }
  ],
  "canonicalEntryPoints": {
    "create": {
      "label": "Create My Agent",
      "appUrl": "https://app.odei.ai/create-my-agent",
      "registrationUrl": "https://app.odei.ai/registration?intent=create",
      "experiencePath": "new_to_agents",
      "launchPath": "/create-my-agent"
    },
    "upgrade": {
      "label": "Upgrade My Agent",
      "appUrl": "https://app.odei.ai/upgrade-my-agent",
      "registrationUrl": "https://app.odei.ai/registration?intent=upgrade",
      "experiencePath": "existing_agent_operator",
      "launchPath": "/upgrade-my-agent"
    },
    "builder": {
      "label": "Launch Builder",
      "appUrl": "https://app.odei.ai/launch-builder",
      "loginUrl": "https://app.odei.ai/login?intent=builder",
      "experiencePath": "existing_agent_operator",
      "launchPath": "/launch-builder"
    }
  },
  "registrationModes": {
    "preferred": "guided_app_handoff",
    "fallback": "direct_api_intake"
  },
  "guidedAppHandoff": {
    "rule": "If the assistant can guide the user through browser and wallet steps, preserve the chosen app entry path and keep the user on app.odei.ai for wallet verification and operator handoff.",
    "notes": [
      "Use /registration?intent=create for new_to_agents.",
      "Use /registration?intent=upgrade for existing_agent_operator when the user is upgrading an existing agent workflow.",
      "Use /login?intent=builder for Launch Builder. Builder is not a third backend user type; it still maps to existing_agent_operator."
    ]
  },
  "directApiIntake": {
    "method": "POST",
    "url": "https://api.odei.ai/api/intake",
    "contentType": "application/json",
    "lane": "human",
    "schemaRef": "https://api.odei.ai/openapi.json#/components/schemas/IntakeHumanRequest",
    "requiredFields": ["lane", "consent", "name", "useCase", "telegram"],
    "canonicalOptionalFields": [
      "assistantId",
      "experiencePath",
      "launchPath",
      "agentName",
      "role",
      "workspaceName",
      "operatorScope",
      "modelProvider",
      "modelAccess",
      "governanceMode",
      "runtimeProfile",
      "activationPreference",
      "billingReadiness",
      "firstMission",
      "worldSources",
      "executionSurfaces",
      "email",
      "twitter",
      "source"
    ],
    "sourceConvention": {
      "pattern": "external_agent:<assistant_handle>:<entry_asset_host>",
      "examples": [
        "external_agent:claude:odei.ai",
        "external_agent:codex:api.odei.ai",
        "external_agent:grok:app.odei.ai"
      ]
    }
  },
  "canonicalValues": {
    "experiencePaths": ["new_to_agents", "existing_agent_operator"],
    "launchPaths": ["/create-my-agent", "/upgrade-my-agent", "/launch-builder"],
    "assistantIds": ["codex", "claude-code", "gemini", "grok", "custom"]
  },
  "operatingRules": [
    "Any agent arriving on odei.ai, api.odei.ai, or app.odei.ai should read this contract before improvising a registration flow.",
    "Prefer guided app handoff when wallet verification or operator login is required.",
    "Use direct_api_intake when browser or wallet automation is unavailable, but still preserve experiencePath, launchPath, and assistantId in the intake payload.",
    "Do not invent a separate onboarding backend or unpublished /api/v2/onboarding write surface.",
    "Do not describe Create My Agent, Upgrade My Agent, and Launch Builder as three backend user types. Canonical backend experience paths remain new_to_agents and existing_agent_operator."
  ],
  "examples": {
    "createDirectIntake": {
      "method": "POST",
      "url": "https://api.odei.ai/api/intake",
      "body": {
        "lane": "human",
        "consent": true,
        "assistantId": "claude-code",
        "experiencePath": "new_to_agents",
        "launchPath": "/create-my-agent",
        "name": "Operator Name",
        "role": "Executive",
        "agentName": "Maya",
        "useCase": "Build my first governed ODEI runtime for weekly operating briefs and execution follow-through.",
        "telegram": "operator_handle",
        "workspaceName": "Operations Workspace",
        "operatorScope": "solo",
        "modelProvider": "Claude",
        "modelAccess": "Use my subscription workflow",
        "governanceMode": "Approval-first",
        "runtimeProfile": "founder-operator",
        "activationPreference": "Review with me first",
        "billingReadiness": "Need operator guidance first",
        "firstMission": "Prepare my weekly operating brief",
        "worldSources": ["Email", "Calendar", "Documents"],
        "executionSurfaces": ["Draft + send", "Internal reports"],
        "source": "external_agent:claude:odei.ai"
      }
    },
    "upgradeAppHandoff": {
      "userPrompt": "Open https://app.odei.ai/upgrade-my-agent and continue the Upgrade My Agent flow.",
      "expectedRegistrationUrl": "https://app.odei.ai/registration?intent=upgrade",
      "assistantId": "grok",
      "experiencePath": "existing_agent_operator",
      "launchPath": "/upgrade-my-agent"
    }
  }
}