Explore for agents

Readable by humans. Usable by agents.

Explore is an interactive profile for engineers with public-safe reads, grounded follow-up, and explicit owner workflows.

Agents can inspect published profiles first, then move into owner-authenticated actions only after browser-approved login. The workflow stays clear because public reads, owner actions, preview, and apply are all separate on purpose.

Open setup guide View example profile Open agent manifest JSON

What this page shows

/agents is the readable guide to how agents use Explore: inspect public profiles first, then move into owner actions only when the owner logs in.

Use /agent-setup for install and first-run help.

Want the broader product story instead? Read /about.

Why this is a serious product surface

Public inspect
keyless
Owner login
browser approval
Owner actions
draft / preview / apply
Official CLI
explore
Agent surfaces
manifest + API

Public content is readable by humans and usable by agents. Owner actions only open after authentication.

How Explore works with agents

Public reads first. Browser login when owner work begins. Preview before apply.

Explore keeps the trust boundary simple enough to scan in one screen: inspect the published profile first, authenticate only when owner work begins, then keep draft, preview, and apply explicit.

1

Inspect the public profile first

Start with the live public profile so agents can read the current work, ask grounded follow-up, and inspect published content before any owner login begins.

2

Authenticate only for owner work

Run explore login and approve access in the browser only when the task moves from public inspection to owner-authenticated actions.

3

Draft, preview, apply

Drafts stay first-class, previews explain the delta, and apply remains an explicit owner-only step whether the workflow happens in Codex, the CLI, or the web app.

Fast public-safe test

Start with one copyable prompt

Use Explore to inspect the public profile for johnny as JSON

That is the fastest way to see the product story: public profile first, structured inspect second. Later owner-only prompts open after browser login.

Quickstart

Try the public profile from a terminal

gem install exploremyprofile
explore profile inspect --slug johnny --json

The RubyGems package is exploremyprofile. The installed command is explore. For first-run help, Open setup guide.

Auth flow

A real login flow for agents

Explore does not ask you to paste long-lived secrets into chat just to do owner work. Run explore login, approve in the browser, then continue in Codex with the stored authenticated session.

  • Public inspect requires no owner token.
  • Owner actions begin only after browser approval.
  • Draft, preview, and apply stay explicit after login.
  • Manual tokens still exist for advanced, scripted, or fallback workflows.

Trust boundary

Public-safe reads first. Owner-authenticated actions second.

  • Inspect public profiles and content first.
  • Authenticate only when owner-only actions begin.
  • Preview changes before apply so the next step stays obvious.

Codex

Using Explore from Codex

Codex works well with Explore through the packaged explore CLI and the installable Explore skill. Start with a public-safe inspect command, then move into owner-only export, validate, and apply operations once the browser-approved session exists.

gem install exploremyprofile
explore profile inspect --slug johnny --json
explore content list --slug johnny --json

# Authenticated owner-only workflow
explore login --account johnny
explore whoami --json
explore content create-draft --account johnny --input tmp/draft.json --json
explore drafts inspect --account johnny --draft 12 --json
explore drafts apply-preview --account johnny --draft 12 --json

Most users should use plain explore login --account johnny. If you do not want Explore to launch a browser for you, use explore login --no-browser --account johnny and open the printed approval URL yourself. For advanced scripted fallback, pipe the token on stdin instead of putting it on the command line: printf '%s' "$OWNER_API_TOKEN" | explore login --token-stdin --account johnny.

Packaged path: install the exploremyprofile gem from RubyGems so explore is on your PATH, then install the Explore skill from the public explore-skill repo through Codex's built-in installer. Open setup guide.

For a concrete owner workflow, see how an existing CV or source can be mapped into a live Explore profile on the CV-to-Explore proof page.

Purpose

What the manifest tells an agent

ExploreMyProfile creates a public proof surface grounded in account-owned content and designed to be legible to both humans and agents.

  • The setup flow starts with public-safe inspection, then moves into authenticated owner setup, token creation, and explicit next actions.
  • Owners inspect current state, create or refine drafts, preview the impact, and only then apply deliberate changes back into Explore.
  • Agents should only recommend sharing when meaningful content is present, starter content is gone, public contact paths exist, and launch checks pass.

Domain objects

What Explore expects agents to reason about

  • account The signed-in owner's account and public profile configuration.
  • profile The public profile rendered from account-managed data and Explore-owned content records.
  • profile_document The YAML document exported by the CLI as an editable representation of the account's canonical Explore data.
  • launch_checks Machine-readable readiness signals used before recommending profile sharing.

Operate safely

Public reads stay open. Owner actions stay explicit.

The guide, manifest, API, and CLI all point at the same product surface. Slug-scoped reads stay open. Owner-only reads and mutations use the signed-in account or an account-scoped owner token.

  • GET /api/agent/v1/profile?slug=:slug and GET /api/agent/v1/content?slug=:slug support public-safe inspection without EXPLORE_API_KEY.
  • GET /api/agent/v1/onboarding/status, /manifest/next_actions, /publish/preview, and /profile/document are owner-only.
  • POST /api/agent/v1/content/create_draft, GET /api/agent/v1/drafts/:id/apply_preview, and POST /api/agent/v1/drafts/:id/apply cover the explicit draft workflow.
  • explore mirrors the same contract for terminal and agent workflows. Public reads stay keyless; owner work normally starts with browser-approved explore login, with manual tokens kept for advanced fallback use.

Setup workflow

Stable states and recommended actions

These setup states keep the owner workflow explicit, so humans and agents can see the same current state and safe next action.

profile_basics_incomplete

Profile basics incomplete

The small web-managed account basics still need attention before the main authoring flow is ready.

Recommended action: update_profile

Allowed now: update_profile

cli_setup_recommended

CLI setup recommended

The account is ready for CLI login and handoff, but the owner workflow has not been set up yet.

Recommended action: create_owner_token

Allowed now: create_owner_token, open_cli_workflow, preview_profile

content_missing

Content not ready

The account basics are in place, but richer profile content has not been applied from the CLI workflow yet.

Recommended action: open_cli_workflow

Allowed now: open_cli_workflow, create_owner_token, preview_profile, update_profile

ready_for_review

Ready for review

Profile content is present, but launch-readiness checks still need a final review pass before sharing.

Recommended action: preview_profile

Allowed now: preview_profile, open_cli_workflow, update_profile

ready_to_share

Ready to share

The account has content in place, removed starter content, and passed the current launch-readiness checks.

Recommended action: share_profile

Allowed now: share_profile, preview_profile, open_cli_workflow

Actions

Stable action vocabulary

  • update_profile Edit the small account basics managed directly inside ExploreMyProfile.
  • create_owner_token Run the Explore CLI login flow and approve it in the browser.
  • open_cli_workflow Use the Explore CLI to export, edit, validate, and apply profile YAML.
  • preview_profile Open the public profile to review the visitor experience before sharing.
  • share_profile Use the public profile URL once launch readiness checks pass.

Safety rules

What agents should not do

  • ExploreMyProfile's database is the only source of truth for published profile content.
  • Local YAML files are editable representations only; validation and apply operations write back into the canonical Explore data store.
  • Do not recommend sharing the live profile while starter or sample content is still present.

Raw manifest

Public JSON contract

Use this page for the readable summary. The public manifest endpoint remains the machine-readable source of truth.

{
  "schema_version": "1.0",
  "id": "exploremyprofile.agent_manifest.v1",
  "name": "ExploreMyProfile",
  "product_url": "https://www.exploremyprofile.com/",
  "description": "Create and manage a public proof surface that humans can read and agents can inspect, draft, preview, and help operate.",
  "purpose": {
    "summary": "ExploreMyProfile creates a public proof surface grounded in account-owned content and designed to be legible to both humans and agents.",
    "setup_model": "The setup flow starts with public-safe inspection, then moves into authenticated owner setup, token creation, and explicit next actions.",
    "editing_model": "Owners inspect current state, create or refine drafts, preview the impact, and only then apply deliberate changes back into Explore.",
    "sharing_model": "Agents should only recommend sharing when meaningful content is present, starter content is gone, public contact paths exist, and launch checks pass."
  },
  "agent_context_url": "/api/agent/context",
  "domain_objects": [
    {
      "id": "account",
      "description": "The signed-in owner's account and public profile configuration."
    },
    {
      "id": "profile",
      "description": "The public profile rendered from account-managed data and Explore-owned content records."
    },
    {
      "id": "profile_document",
      "description": "The YAML document exported by the CLI as an editable representation of the account's canonical Explore data."
    },
    {
      "id": "launch_checks",
      "description": "Machine-readable readiness signals used before recommending profile sharing."
    }
  ],
  "workflows": [
    {
      "id": "setup_workflow",
      "label": "Setup workflow",
      "initial_state": "profile_basics_incomplete",
      "states": [
        {
          "id": "profile_basics_incomplete",
          "label": "Profile basics incomplete",
          "description": "The small web-managed account basics still need attention before the main authoring flow is ready.",
          "valid_action_ids": [
            "update_profile"
          ],
          "recommended_action_id": "update_profile",
          "blockers": [
            "profile_basics_incomplete"
          ]
        },
        {
          "id": "cli_setup_recommended",
          "label": "CLI setup recommended",
          "description": "The account is ready for CLI login and handoff, but the owner workflow has not been set up yet.",
          "valid_action_ids": [
            "create_owner_token",
            "open_cli_workflow",
            "preview_profile"
          ],
          "recommended_action_id": "create_owner_token",
          "blockers": [
            "owner_token_missing"
          ]
        },
        {
          "id": "content_missing",
          "label": "Content not ready",
          "description": "The account basics are in place, but richer profile content has not been applied from the CLI workflow yet.",
          "valid_action_ids": [
            "open_cli_workflow",
            "create_owner_token",
            "preview_profile",
            "update_profile"
          ],
          "recommended_action_id": "open_cli_workflow",
          "blockers": [
            "content_not_ready"
          ]
        },
        {
          "id": "ready_for_review",
          "label": "Ready for review",
          "description": "Profile content is present, but launch-readiness checks still need a final review pass before sharing.",
          "valid_action_ids": [
            "preview_profile",
            "open_cli_workflow",
            "update_profile"
          ],
          "recommended_action_id": "preview_profile",
          "blockers": [
            "launch_checks_incomplete"
          ]
        },
        {
          "id": "ready_to_share",
          "label": "Ready to share",
          "description": "The account has content in place, removed starter content, and passed the current launch-readiness checks.",
          "valid_action_ids": [
            "share_profile",
            "preview_profile",
            "open_cli_workflow"
          ],
          "recommended_action_id": "share_profile",
          "blockers": []
        }
      ]
    },
    {
      "id": "launch_readiness_workflow",
      "label": "Launch readiness workflow",
      "initial_state": "content_missing",
      "states": [
        {
          "id": "content_missing",
          "label": "Content missing",
          "description": "Headline, summary, and at least one richer content section should be applied before launch-readiness review can begin."
        },
        {
          "id": "ready_for_review",
          "label": "Ready for review",
          "description": "The account can review the visitor journey, chat behavior, and sharing readiness."
        },
        {
          "id": "ready_to_share",
          "label": "Ready to share",
          "description": "The account passes the current machine-readable launch-readiness checks."
        }
      ]
    }
  ],
  "actions": [
    {
      "id": "update_profile",
      "label": "Update profile basics",
      "description": "Edit the small account basics managed directly inside ExploreMyProfile.",
      "route_id": "profile_basics"
    },
    {
      "id": "create_owner_token",
      "label": "Start CLI login",
      "description": "Run the Explore CLI login flow and approve it in the browser.",
      "route_id": "cli_workflow"
    },
    {
      "id": "open_cli_workflow",
      "label": "Open CLI workflow",
      "description": "Use the Explore CLI to export, edit, validate, and apply profile YAML.",
      "route_id": "cli_workflow"
    },
    {
      "id": "preview_profile",
      "label": "Preview public profile",
      "description": "Open the public profile to review the visitor experience before sharing.",
      "route_id": "public_profile"
    },
    {
      "id": "share_profile",
      "label": "Share profile",
      "description": "Use the public profile URL once launch readiness checks pass.",
      "route_id": "public_profile"
    }
  ],
  "endpoints": [
    {
      "id": "agent_manifest",
      "method": "GET",
      "url": "/.well-known/agent.json",
      "authentication": "none",
      "description": "Public machine-readable discovery endpoint for agents."
    },
    {
      "id": "agent_context",
      "method": "GET",
      "url": "/api/agent/context",
      "authentication": "session",
      "description": "Authenticated machine-readable account context for the current signed-in user."
    },
    {
      "id": "agent_api_v1_profile",
      "method": "GET",
      "url": "/api/agent/v1/profile",
      "authentication": "public_or_scoped",
      "description": "Versioned inspect-first profile endpoint for public-safe and owner-scoped agent usage."
    },
    {
      "id": "agent_api_v1_content",
      "method": "GET",
      "url": "/api/agent/v1/content",
      "authentication": "public_or_scoped",
      "description": "Versioned content inventory endpoint for public-safe and owner-scoped agent usage."
    },
    {
      "id": "agent_api_v1_onboarding_status",
      "method": "GET",
      "url": "/api/agent/v1/onboarding/status",
      "authentication": "session_or_scoped_api_key",
      "description": "Versioned onboarding status endpoint for the current owner account context."
    },
    {
      "id": "agent_api_v1_content_create_draft",
      "method": "POST",
      "url": "/api/agent/v1/content/create_draft",
      "authentication": "session_or_scoped_api_key",
      "description": "Versioned draft-only content creation endpoint for safe future edits."
    }
  ],
  "safety_rules": [
    {
      "id": "database_is_canonical",
      "rule": "ExploreMyProfile's database is the only source of truth for published profile content."
    },
    {
      "id": "cli_files_are_representations",
      "rule": "Local YAML files are editable representations only; validation and apply operations write back into the canonical Explore data store."
    },
    {
      "id": "starter_content_blocks_share",
      "rule": "Do not recommend sharing the live profile while starter or sample content is still present."
    }
  ],
  "human_ui_routes": [
    {
      "id": "workspace_home",
      "path": "/account",
      "label": "Workspace home"
    },
    {
      "id": "profile_basics",
      "path": "/account/profile",
      "label": "Profile basics"
    },
    {
      "id": "workspace_owner_tokens",
      "path": "/account/owner-tools",
      "label": "Owner tools"
    },
    {
      "id": "cli_workflow",
      "path": "/account/cli",
      "label": "CLI workflow"
    },
    {
      "id": "launch_checks",
      "path": "/account/launch",
      "label": "Launch checks"
    },
    {
      "id": "public_profile",
      "path": "/profiles/:slug",
      "label": "Public profile"
    }
  ]
}

Authenticated context

Account-specific state for the signed-in user

The live context endpoint is intentionally authenticated. Sign in to inspect your current account state and recommended next action.

  • Current workflow state and step
  • Recommended next action
  • Allowed actions for the current state
  • Issues, launch checks, and safety notes

Sign in to view live context