# GHWD Developer Portal

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

## Quickstart (agents)

```bash
# 1. Read when-to-use + canonical URLs
curl -s https://ghwd.com.br/llms.txt

# 2. Fetch Markdown instead of HTML
curl -s -H "Accept: text/markdown" https://ghwd.com.br/
curl -s -H "Accept: text/markdown" https://ghwd.com.br/services/

# 3. Confirm unknown paths are real 404s
curl -s -o /dev/null -w "%{http_code}\n" https://ghwd.com.br/path-that-does-not-exist
```

## Discovery endpoints

| Resource | URL | Content-Type |
|---|---|---|
| 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

## API keys & sandbox

Project API keys (RAG backends, commerce sync, automation webhooks) are provisioned per engagement — not via public self-serve signup.

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, read-only):** use the curl commands above against production discovery 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.