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 through explore setup. The setup guide shows the current recommended path, the Explore CLI is the underlying compatibility layer for shell-capable agent environments, and the browser only appears when signup, sign-in, or approval is required.

Get started with Explore 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 through the setup/auth path only when needed.

Use /agent-setup for the current recommended setup path.

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. Start with your agent. Browser auth only when owner work begins.

Explore keeps the trust boundary simple enough to scan in one screen: inspect the published profile first, use the setup guide when owner work begins, let the browser handle auth only when needed, 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

Run setup only for owner work

Run explore setup when the task moves from public inspection to owner-authenticated actions. The setup guide covers the current recommended path, and Explore opens the browser only if signup, sign-in, or approval is needed.

3

Draft, preview, apply

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

Fast public-safe test

Start with a natural-language ask

Inspect my current profile and suggest improvements.

That is the fastest way to see the product story: ask naturally first, let Explore use the CLI underneath, and only fall back to raw commands when you are deliberately driving a manual workflow.

Shared prompt set

Use the same small set of asks across the product

Set up Explore.
Inspect my current profile and suggest improvements.
Import my CV into my Explore profile.
Add my blog or writing to my Explore profile and show me the preview first.
Show me my public profile.
Update my summary and links.

Natural language is the default experience. The CLI is the substrate underneath, and raw flags belong in advanced or manual fallback paths.

Auth flow

A real setup and login flow for agents

Explore does not ask you to paste long-lived secrets into chat just to do owner work. Start with explore setup through the setup guide, use the CLI as the broader compatibility layer, and let the browser handle signup, sign-in, or approval only when needed.

Public inspect requires no owner token.
Owner actions begin with the setup guide and browser auth only when Explore needs it.
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.

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 CLI underneath.

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 and show me the preview first.
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.

If you are using another shell-capable agent environment, the Explore CLI is the supported compatibility layer to build on right now.

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.

Show manual CLI examples

gem install exploremyprofile
explore setup

# Existing-account or explicit login path
explore login --account johnny
explore whoami --json
explore export profile --account johnny --format yaml > profile.yaml
explore validate profile.yaml
explore apply profile.yaml --account johnny

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

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 explore setup, while explicit login and manual tokens stay in the advanced/manual 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.

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 Start the Explore setup or login flow and approve it in the browser only when needed.
open_cli_workflow Use the setup guide and CLI workflow to inspect, refine, preview, and apply profile updates.
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://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, 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": "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."
    }
  ],
  "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": "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