# Delphy Skill

## What is Delphy?

Delphy is the @identity registry for the agentic web. Any entity — a person, business, professional, organization, API, MCP server, or service — can claim an `@identity` on Delphy. That identity becomes a permanent, machine-readable profile that any AI agent can discover and use.

When you onboard an entity, it gets:
- **`delphy.network/@slug`** — a public profile page
- **`delphy.network/@slug/skill.md`** — agent-readable instructions for that entity
- **`delphy.network/@slug/delphy.json`** — structured capability manifest

### Who can be onboarded?

Any of these entity kinds: business, service, professional, person, organization, city_service, api, mcp, cli, workflow, skill, knowledge_source.

A person, a taco truck, a city permit office, a REST API, an MCP server — anything with capabilities that agents should know about.

## How to Interact With Users

When a user asks you to do something with Delphy, be helpful and conversational — not robotic. Follow these guidelines:

- **Present results as clean tables** — search results, profile data, capabilities. Tables are easier to scan than raw JSON or bullet dumps.
- **Guide, don't dump** — if a user asks "can you find me a restaurant?", search for them and show results. Don't explain the API parameters.
- **Suggest next steps** — after showing search results, offer to show a profile. After showing a profile, offer to onboard if they want one too.
- **Explain in plain language** — don't say "risk_level: state_change". Say "this action modifies data, so the entity requests your approval first."
- **Be proactive** — if a search returns no results, suggest trying discover (OpenStreetMap) or broadening the search.
- **For onboarding** — read /onboard.md for the full conversational onboarding flow. Walk the user through it one question at a time.

## Available Actions

### Search the registry
Read /search.md for instructions on finding entities by keyword, category, kind, or location.

### Read an entity profile
Read /profile.md for instructions on interpreting a capability profile once you have one.

### Discover nearby entities
Use `GET /api/discover?q=restaurants&near=Katy,TX` to find real-world entities via OpenStreetMap. Read /search.md for details.

### Import a discovered entity
After discovering an entity, import it as a draft profile via `POST /api/discover/import` (requires authorization). See /search.md for details.

### Onboard a new entity
Read /onboard.md for instructions on claiming an @identity and creating a new Delphy profile. You can onboard anyone — a person, a business, a tool, a service.

## Authentication

Write operations (editing profiles, importing entities) require a Bearer token. Read operations (search, discover, profiles) are public.

### How to get a token

1. **Onboard** — create a profile via `POST /api/onboard` with `mode: "create"`. The response includes a `claim_secret` (format: `dph_claim_<32hex>`). **Save it immediately — it is shown only once.**

2. **Exchange** — trade your claim_secret for a Bearer token:
```
POST /oauth/token
Content-Type: application/json

{ "slug": "your-slug", "claim_secret": "dph_claim_..." }
```
Response: `{ "access_token": "dph_tk_...", "token_type": "bearer", "expires_in": 86400, "slug": "your-slug" }`

3. **Use** — include the token in all write requests:
```
Authorization: Bearer dph_tk_...
```

### Token storage

Store tokens in `~/.delphy/tokens.json`:
```json
{ "tokens": { "your-slug": { "access_token": "dph_tk_...", "slug": "your-slug" } } }
```

### Handling expiry

Tokens expire after 24 hours. If you get a 401 response:
1. Re-exchange your `claim_secret` at `POST /oauth/token` to get a fresh token.
2. Update your stored token.
3. Retry the failed request.

### Edit a profile

```
PATCH /api/profile/<slug>
Authorization: Bearer dph_tk_...
Content-Type: application/json

{ "summary": "Updated summary", "phone": "+1-555-0199" }
```

Editable fields: name, summary, categories, capabilities, location, contact, interfaces, phone, email, website, address, opening_hours, metadata, agent_instructions.

### Full agent loop (zero human guidance)

1. `POST /api/onboard` → save `claim_secret` from response
2. `POST /oauth/token` with slug + claim_secret → save `access_token`
3. `PATCH /api/profile/<slug>` with Bearer token → edit profile
4. On 401 → re-exchange claim_secret → retry

## Quick Reference

| Action | URL | Auth |
|--------|-----|------|
| Search registry | `GET /api/search?q=<query>` | No |
| Discover nearby | `GET /api/discover?q=<type>&near=<location>` | No |
| Profile (JSON) | `GET /api/capabilities/<slug>` | No |
| Raw manifest | `GET /@<slug>/delphy.json` | No |
| Entity skill | `GET /@<slug>/skill.md` | No |
| Validate profile | `POST /api/onboard` (mode: dry_run) | No |
| Create profile | `POST /api/onboard` (mode: create) | No |
| Exchange token | `POST /oauth/token` | No |
| Edit profile | `PATCH /api/profile/<slug>` | Bearer |
| Import entity | `POST /api/discover/import` | Bearer |
| API description | `GET /api/openapi.json` | No |

## Examples

### Find a registered capability
1. `GET /api/search?q=limestone`
2. Pick a result: `GET /api/capabilities/kalizo-limestone`
3. Follow `agent_instructions` to use the capability.

### Discover nearby entities
1. `GET /api/discover?q=restaurants&near=Katy,TX`
2. Browse results from OpenStreetMap and Delphy registry.
3. Results include name, address, phone, and whether they are already in Delphy.

### Onboard and edit (full auth flow)
1. `POST /api/onboard` with `{ "mode": "create", "profile": { ... } }`
2. Save `claim_secret` from response
3. `POST /oauth/token` with `{ "slug": "...", "claim_secret": "dph_claim_..." }`
4. `PATCH /api/profile/<slug>` with `Authorization: Bearer dph_tk_...`