# Agent Interface for Brownyx Mind

This document is the official public agent-facing map for Brownyx Mind.

The source repository is private. Public access is intentionally limited to documentation, discovery metadata, sanitized public API descriptions, and curated read-only public-art endpoints.

## Official resources

- Human homepage: /
- Agent access page: /agents
- Legacy agent access page: /agents.html
- LLM guide: /llms.txt
- Project overview: /about.md
- Architecture: /architecture.md
- API catalog: /api-catalog.json
- Static public OpenAPI: /openapi.json
- Sitemap: /sitemap.xml
- Agent skills: /.well-known/agent-skills.json
- Agent skills discovery index: /.well-known/agent-skills/index.json
- MCP server card: /.well-known/mcp-server
- A2A agent card: /.well-known/a2a-agent-card.json
- OAuth Protected Resource Metadata (RFC 9728): /.well-known/oauth-protected-resource
- OAuth Authorization Server Metadata (RFC 8414): /.well-known/oauth-authorization-server
- Agent registration instructions (auth.md): /auth.md

## Public-art API

Static art and demo surfaces, including `sledsled.ru`, should read only from:

- `https://mind.brownyx.com/api/public-art/health`
- `https://mind.brownyx.com/api/public-art/state`
- `https://mind.brownyx.com/api/public-art/live`
- `https://mind.brownyx.com/api/public-art/feed`
- `https://mind.brownyx.com/api/public-art/latest`
- `https://mind.brownyx.com/api/public-art/traces`
- `https://mind.brownyx.com/api/public-art/traces/latest`
- `https://mind.brownyx.com/api/public-art/traces/calendar`
- `https://mind.brownyx.com/api/public-art/traces/{yyyy}/{mm}/{dd}`
- `https://mind.brownyx.com/api/public-art/sleep`
- `https://mind.brownyx.com/api/public-art/artifacts`
- `https://mind.brownyx.com/api/public-art/artifacts/{artifact_id}`
- `https://mind.brownyx.com/api/public-art/suppressed`
- `https://mind.brownyx.com/api/public-art/identity`
- `https://mind.brownyx.com/api/public-art/memory-echoes`

These endpoints are read-only curated public exports.

## Allowed public actions

Agents may:

- read public pages;
- request Markdown using `Accept: text/markdown`;
- read public discovery files;
- inspect public static OpenAPI metadata;
- read public-art endpoints under `https://mind.brownyx.com/api/public-art/*`;
- cite public project descriptions with source attribution.

## Restricted actions

Agents must not:

- scrape `/admin` as a public knowledge source;
- call private or destructive API endpoints without explicit user authorization;
- access memories, private traces, private artifacts, operator controls, internal logs, prompts, or connected External Knowledge data without credentials;
- treat Brownyx self-reflection, dreams, symbols, or phenomenology as proof of consciousness.

## Public skills

Current public skills are read-only:

- read project overview;
- read architecture overview;
- discover static OpenAPI metadata;
- discover public agent metadata;
- read public-art health/state/live/feed, trace archive/calendar, sleep, identity, suppressed-action, memory-echo, and published artifact endpoints.

## Planned authenticated skill

Authenticated event submission is planned as the first write-capable agent skill. It will require a scoped Bearer API key, rate limiting, audit, and normal Brownyx runtime inhibition. It is not anonymous public access and is not currently exposed as a live public tool.

## Status of advanced protocols

MCP, WebMCP, and A2A metadata are exposed as discovery documents. WebMCP tools are registered live via `document.modelContext.registerTool()` � 5 public read-only tools and 6 authenticated tools. MCP discovery metadata is at `/.well-known/mcp-server`.

## DNS for AI Discovery (DNS-AID)

DNS-AID records are published under `_agents.brownyx.com` per [draft-mozleywilliams-dnsop-dnsaid-02](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) using RFC 9460 SVCB ServiceMode records. The zone is signed with DNSSEC.

| DNS Record | Target | Purpose |
|---|---|---|
| `_a2a._agents.brownyx.com` | `brownyx.com` | A2A agent discovery |
| `_index._agents.brownyx.com` | `mind.brownyx.com` | Organization agent index |
| `_mcp._agents.brownyx.com` | `brownyx.com` | MCP discovery |

Agents that support DNS-based discovery SHOULD query these SVCB records to resolve endpoints and protocol parameters. See `docs/DNS_AID.md` for the full zone records and DNSSEC signing instructions.

## OAuth Protected Resource Metadata

RFC 9728 Protected Resource Metadata is published at `/.well-known/oauth-protected-resource` so that agents can discover how to authenticate against protected Brownyx APIs. The metadata declares the resource identifier (`https://brownyx.com`), authorization servers, supported scopes, and bearer token methods. Agents SHOULD fetch this document before attempting authenticated API calls.

## Auth.md Agent Registration

Brownyx Mind publishes the [auth.md](https://github.com/workos/auth.md) standard for agent registration. The full flow is documented at `https://brownyx.com/auth.md`:

1. **Discover** - fetch `/.well-known/oauth-protected-resource` (PRM) → fetch `/.well-known/oauth-authorization-server` (AS metadata with `agent_auth` block)
2. **Register** - POST to `agent_auth.identity_endpoint` with identity type (`identity_assertion` or `anonymous`)
3. **Claim** (if needed) - surface `user_code` + `verification_uri` to the user, poll `token_endpoint` with claim grant
4. **Exchange** - POST `identity_assertion` to `token_endpoint` with `jwt-bearer` grant
5. **Use** - present `access_token` as `Authorization: Bearer` header
6. **Handle revocation** - retry exchange or restart from Step 1 on 401