Readable by humans. Usable by agents.

How Explore works with agents

Public reads first. Shared CLI/API flow second. Browser auth only when owner work begins.

Explore keeps the trust boundary simple enough to scan in one screen: inspect the published profile first, move into the shared Explore CLI and API flow when owner work begins, let the browser handle auth only when needed, then keep draft, preview, and apply explicit.

Owner workflow

Use Explore through your agent first

Install the packaged explore CLI, run explore setup, then keep the default workflow simple: ask naturally for setup, inspection, import, preview, and profile updates while Explore uses the same CLI contract underneath. Optional helpers can improve the experience in some tools, but they are not required for basic usage.

After a successful profile update, Explore should point you back to the live profile and include the preview link when that helps.

• Import my CV into my Explore profile.
• Add my blog or writing to my Explore profile.
• Inspect my current profile and suggest improvements.

The normal Explore path is not raw flags first. Public reads stay open, owner work begins with setup only when needed, and the browser stays limited to signup, sign-in, or approval handoff.

Packaged path: install the exploremyprofile gem from RubyGems so explore is on your PATH, then use the setup guide for the current recommended path.

Codex, Claude Code, OpenCode, and Cursor are supported today, and all four sit on the same Explore CLI and API contract. Tool-specific helpers stay thin and optional.

Other tools that can run shell commands should also work with Explore's shared CLI flow, with fuller support rolling out very soon.

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.

Advanced / manual fallback

Keep raw CLI commands as a secondary path

Raw commands still matter for manual, scripted, or fallback workflows. They are intentionally secondary to the natural-language-first setup path, and they are the shared substrate underneath all supported tools and any optional helpers.

gem install exploremyprofile
explore commands --json
explore setup
explore setup claude --write

# Inspect one command in agent-readable form
explore profile inspect --help --agent

# Existing-account or explicit login path
explore login --account johnny
explore whoami --json
explore export profile --account johnny --output tmp/profile.yml
explore validate tmp/profile.yml
explore preview profile tmp/profile.yml --account johnny --json
explore apply tmp/profile.yml --account johnny --expected-fingerprint sha256:... --json

# Advanced manual fallback
explore login --no-browser --account johnny
printf '%s' "$OWNER_API_TOKEN" | explore login --token-stdin --account johnny

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.
• For new content, use POST /api/agent/v1/content/create_draft first, then GET /api/agent/v1/drafts/:id, GET /api/agent/v1/drafts/:id/apply_preview, and POST /api/agent/v1/drafts/:id/apply.
• POST /api/agent/v1/content/propose_update is audit-only and is for suggesting updates to an existing target or the profile target, not for creating a new post.
• explore mirrors the same contract for terminal and agent workflows. Public reads stay keyless; owner work normally starts with explore setup, supported tools sit on the same shared CLI flow, thin optional helpers stay on top, and explicit login/manual tokens stay in the advanced fallback path.

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.

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.johnnybutler.dev/",
  "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, inspect the draft, preview the impact, and only then apply deliberate changes back into Explore. Audit-only proposals are for existing targets, not brand-new content.",
    "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": "Start the Explore setup or login flow and approve it in the browser only when needed.",
      "route_id": "cli_workflow"
    },
    {
      "id": "open_cli_workflow",
      "label": "Open CLI workflow",
      "description": "Use the setup guide and CLI workflow to inspect, refine, preview, and apply profile updates.",
      "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."
    },
    {
      "id": "agent_api_v1_content_propose_update",
      "method": "POST",
      "url": "/api/agent/v1/content/propose_update",
      "authentication": "session_or_scoped_api_key",
      "description": "Versioned audit-only proposal endpoint for suggested updates to an existing target or the profile target."
    }
  ],
  "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."
    },
    {
      "id": "new_content_starts_with_drafts",
      "rule": "For new posts, projects, or experiences, start with content.create_draft, then drafts.inspect, drafts.apply_preview, and drafts.apply. Use content.propose_update only for audit-only suggestions to an existing target or the profile target."
    }
  ],
  "human_ui_routes": [
    {
      "id": "workspace_home",
      "path": "/account",
      "label": "Account settings"
    },
    {
      "id": "profile_basics",
      "path": "/account",
      "label": "Account settings"
    },
    {
      "id": "workspace_owner_tokens",
      "path": "/account/owner-tools",
      "label": "Owner tools"
    },
    {
      "id": "cli_workflow",
      "path": "/agent-setup",
      "label": "Setup guide"
    },
    {
      "id": "launch_checks",
      "path": "/account",
      "label": "Account settings"
    },
    {
      "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