# GHWD Developer Portal

Machine-readable documentation for agents, integrators, and client engineering teams.

## Quickstart (agents)

```bash
# 1. OpenAPI + health
curl -s https://ghwd.com.br/openapi.json | head
curl -s https://ghwd.com.br/api/v1/health

# 2. when-to-use
curl -s https://ghwd.com.br/llms.txt
curl -s https://ghwd.com.br/api/v1/site

# 3. Markdown negotiation
curl -s -H "Accept: text/markdown" https://ghwd.com.br/

# 4. JSON 404 under /api
curl -s -o /dev/null -w "%{http_code}\n" https://ghwd.com.br/api/v1/does-not-exist
curl -s https://ghwd.com.br/api/v1/does-not-exist
```

## Discovery endpoints

| Resource | URL | Content-Type |
|---|---|---|
| OpenAPI | `/openapi.json` | `application/json` |
| Health | `/api/v1/health` | `application/json` |
| Site profile | `/api/v1/site` | `application/json` |
| Catalog | `/api/v1/catalog` | `application/json` |
| Versioning policy | `/api/v1/versioning` | `application/json` |
| Agent-readiness audit | `/api/v1/audit?url=&locale=` | `application/json` |
| Project brief intake | `/api/v1/brief` | `application/json` |
| Agent instructions | `/llms.txt` | `text/plain` |
| AI knowledge index | `/ai-index.md` | `text/markdown` |
| Sitemap | `/sitemap.xml` | `application/xml` |
| Robots | `/robots.txt` | `text/plain` |
| This portal (HTML) | `/developers/` | `text/html` |
| This portal (MD) | `/developers/` with `Accept: text/markdown` | `text/markdown` |

## Content negotiation & AI bot detection

GHWD follows [acceptmarkdown.com](https://acceptmarkdown.com/). Every public page has a markdown text twin.

Apache serves the text variant when **either**:

1. `Accept: text/markdown` is preferred, or
2. The `User-Agent` matches a known AI crawler (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-extended, Bytespider, Amazonbot, etc.)

Humans still get HTML at the same URL (internal rewrite to `{path}/index.md`, not an external redirect). Responses include `Vary: Accept, User-Agent`.

```bash
# Simulate an AI crawler
curl -sI -A "GPTBot/1.0" https://ghwd.com.br/services/
# Expect: content-type: text/markdown
```

Also see: https://ghwd.com.br/agent-instructions.md

## Versioning {#versioning}

The Agent Discovery API uses **URL path versioning** (`/api/v1/...`).

- Breaking changes ship under a new major path (`/api/v2`).
- Deprecated operations set `Deprecation: true` and a `Sunset` HTTP-date (≥ 90 days notice).
- Machine-readable policy: https://ghwd.com.br/api/v1/versioning

## Errors {#errors}

Unknown `/api/*` paths return RFC 9457 `application/problem+json` with `type`, `title`, `status`, `detail`, `code`, and `resolution`.

## Rate limits

Anonymous discovery traffic: **1000 requests / 60 seconds** per client IP. Successful and error responses include IETF `RateLimit` / `RateLimit-*` headers. HTTP 429 includes `Retry-After`.

## CLI

```bash
npx ghwd-cli health
npx ghwd-cli audit https://example.com
npx ghwd-cli audit https://example.com --json
npx ghwd-cli audit https://example.com --prompt
npx ghwd-cli audit https://example.com --deep
npx ghwd-cli skill install all
npx ghwd-cli brief --name "Ana" --email ana@acme.com --message "Preciso de um site agent-ready"
```

### Improve loop

```mermaid
flowchart LR
  A[Audit] --> B[Prioritize fail/warn]
  B --> C[Apply fixes]
  C --> D[Re-audit]
  D -->|still open| B
```

### Where humans find the CLI on the site

```mermaid
flowchart TB
  H[Home /#agent-audit] --> A[/audit/ UI]
  H --> D[/developers/]
  A --> P[Copy AI fix prompt]
  D --> C[CLI · API · MCP · skills]
  D --> R[/products/audit-pro/]
```

`--deep` local (CLI/SDK) is free. HTTP `deep=1` needs **ghwd-audit Pro** Bearer, **PIX** (R$ 97/mo → manual key), or **x402** `PAYMENT-SIGNATURE`, else **402**. Product: https://ghwd.com.br/products/audit-pro/

## Agent-readiness audit {#audit}

Score any public site for agent surfaces (llms.txt, well-known catalogs, OpenAPI, real 404, markdown, JSON-LD) plus SEO/GEO/a11y heuristics:

```bash
curl -s "https://ghwd.com.br/api/v1/audit?url=https://example.com&locale=en"
# or locally (preferred for bulk / deep lab)
npx ghwd-cli audit example.com --json
npx ghwd-cli audit example.com --prompt
npx ghwd-cli audit example.com --deep
npx ghwd-cli skill install ghwd-audit
```

MCP tool: `audit_site` (optional `locale`, optional `deep`). Skill: https://ghwd.com.br/.well-known/agent-skills/ghwd-audit/SKILL.md · UI: https://ghwd.com.br/audit/

## ghwd-audit Pro {#audit-pro}

### deep=1 end-to-end

```mermaid
sequenceDiagram
  participant Client
  participant Audit as audit.php
  participant Keys as audit_keys
  participant X402 as audit_x402
  participant Fac as facilitator

  Client->>Audit: deep=1
  alt Bearer Pro
    Audit->>Keys: ok
    Audit-->>Client: 200 deep
  else Payment-Signature
    Audit->>X402: verify+settle
    X402->>Fac: /verify /settle
    Audit-->>Client: 200 deep + receipt
  else sem pagamento
    Audit-->>Client: 402 PIX + x402 accepts
  end
```

Where it fits: local CLI `--deep` stays free; humans/CI use PIX → Bearer; agents can pay-per-deep via x402; otherwise HTTP **402** with PIX + `accepts`.

Remote deep audit over HTTP for agents/CI, hybrid payments:

```bash
# 402 without key (PIX + x402 accepts when host configured)
curl -si "https://ghwd.com.br/api/v1/audit?url=https://example.com&deep=1" | head

# Pro Bearer (after PIX / contact)
curl -s "https://ghwd.com.br/api/v1/audit?url=https://example.com&deep=1" \
  -H "Authorization: Bearer ghwd_audit_…"
```

Agents may also retry with `PAYMENT-SIGNATURE` (x402 USDC pay-per-deep). Humans: pay PIX when `pix.key` is in the 402 body, send receipt to contact, key issued manually.

Product: https://ghwd.com.br/products/audit-pro/ · request key: https://ghwd.com.br/contact/?intent=audit-pro · auth: https://ghwd.com.br/auth.md

## Project brief intake {#brief}

Agents can open a structured lead without scraping the contact form:

```bash
curl -s -X POST https://ghwd.com.br/api/v1/brief \
  -H 'content-type: application/json' \
  -d '{"name":"Ana","email":"ana@acme.com","message":"Quero tornar meu site agent-ready","site_url":"https://example.com","source":"curl"}'
```

MCP tool: `submit_brief`. Rate-limited; for urgent deals use https://ghwd.com.br/contact/.

## API keys & sandbox

Project integrations are defined per engagement. Public /projects, /jobs and /batch paths are reserved probes, not operational APIs: 401 without token, 501 with a supplied token.

1. Open https://ghwd.com.br/contact/ or email contato@ghwd.com.br with scope and environments needed.
2. Receive sandbox credentials + OpenAPI/webhook docs for that project.
3. Promote to production keys after acceptance tests.

**Sandbox (public discovery):** use the curl commands above against production discovery/audit/brief endpoints. They are safe for agents and CI probes.
## When to integrate

Use GHWD APIs/integrations when building custom storefronts, ERP sync, or AI agents that need GHWD-operated backends. Prefer reading `/llms.txt` before inventing URLs.

## Smithery (MCP registry)

[![Smithery](https://smithery.ai/badge/gustavohip/ghwd)](https://smithery.ai/servers/gustavohip/ghwd)

- Product MCP listing: https://smithery.ai/servers/gustavohip/ghwd
- Docs MCP listing: https://smithery.ai/servers/gustavohip/ghwd-docs
- Upstream: https://ghwd.com.br/mcp

## Audit Pro documentation

Authentication, requests, cache, limits and errors: https://ghwd.com.br/developers/audit-pro/

Product and subscription: https://ghwd.com.br/products/audit-pro/