# Developer portal

> The machine-readable surface of this site: quickstart, authentication, sandbox, and the full endpoint table.

Everything here is a real, public, static document. There is no sign-up form, and this page does not pretend otherwise.

## Quickstart

```sh
curl -sS https://ravicha2.github.io/openapi.json
curl -sS https://ravicha2.github.io/agents.md
curl -sS https://ravicha2.github.io/index.md
```

## Authentication

Public and read-only. See /auth.md for the walkthrough.

## API keys

No API keys are issued and none are needed. The origin is a set of static files; there is nothing a key could gate. If a keyed surface is ever published it will be announced in llms.txt.

## Sandbox

The whole surface is a sandbox: every operation is a GET of a public document. There is no production data to damage, so there is no separate test mode and no fixture server pretending to be one.

## Rate limits

None are imposed in software, because the documents are static. GitHub Pages applies its own fair-use limits to the origin.

## Errors

The 404 documented on each operation is the text/html document GitHub Pages serves for an unmatched path; the request also lands in the SPA, which renders the same message for a browser. RFC 9457 application/problem+json is described by components.schemas.Problem but is not served, and cannot be on static hosting: the origin cannot set a response content type or vary a body by Accept. ADR 0004 records the decision to accept this and state it.

The `application/problem+json` envelope is described in the spec as `components.schemas.Problem` and is not served: this origin cannot set a response content type or vary a body by `Accept`. That is a decision, recorded in `docs/adr/0004-accept-html-404s-on-static-hosting.md`.

## Endpoints

| Path | operationId | Returns | Content type |
| --- | --- | --- | --- |
| `/openapi.json` | `getOpenApiDocument` | This document, as JSON. | `application/json` |
| `/.well-known/mcp/server-card.json` | `getMcpServerCard` | A Server Card. | `application/json` |
| `/.well-known/agent-skills/index.json` | `getAgentSkillsIndex` | The skills index. | `application/json` |
| `/.well-known/agent-card.json` | `getAgentCard` | The agent card. | `application/json` |
| `/.well-known/api-catalog` | `getApiCatalog` | A linkset with one item per service description. | `application/octet-stream` |
| `/.well-known/oauth-protected-resource` | `getProtectedResourceMetadata` | Protected resource metadata. | `application/octet-stream` |
| `/.well-known/ard.json` | `getArdCatalog` | The ARD catalog. | `application/json` |
| `/llms.txt` | `getLlmsTxt` | A plain-text markdown index. | `text/plain` |
| `/llms-full.txt` | `getLlmsFullTxt` | A plain-text markdown dossier. | `text/plain` |
| `/agents.md` | `getAgentsMd` | A markdown guide. | `text/markdown` |
| `/auth.md` | `getAuthMd` | A markdown walkthrough. | `text/markdown` |
| `/index.md` | `getMarkdownHome` | A markdown rendering of the homepage. | `text/markdown` |
| `/.well-known/agent-skills/portfolio/SKILL.md` | `getPortfolioSkill` | A markdown skill document. | `text/markdown` |
| `/sitemap.xml` | `getSitemap` | A sitemap. | `application/xml` |
| `/cv.pdf` | `getCurriculumVitae` | A PDF. | `application/pdf` |

## MCP server

The first-party Model Context Protocol server published with the lit-review-council project advertises its transport in a Server Card at /.well-known/mcp. The Python distribution is https://pypi.org/project/lit-review-council/.

## In-page tools

The page registers three read-only tools — `search-projects`, `get-project`, and `describe-site` — through `document.modelContext` when it loads. They run in a visitor's browser, so they need a browser that exposes `document.modelContext`; registering a tool is not a claim that it is callable remotely, and no HTTP client can invoke one. Every answer they give already exists as a static document: `search-projects` is answered by `llms.txt` and `/projects.md`, `get-project` by the markdown twin of a project page (its path with `.md` appended), and `describe-site` by `llms.txt`, `/openapi.json` and `/sitemap.xml`. The decision is recorded in `docs/adr/0005-webmcp-is-browser-mediated.md`.

---

## Fetching the rest of this site

- This page as HTML: <https://ravicha2.github.io/developers/>
- Concise index: <https://ravicha2.github.io/llms.txt>
- Full dossier: <https://ravicha2.github.io/llms-full.txt>
- When to use this material: <https://ravicha2.github.io/agents.md>
- API description (OpenAPI 3.1): <https://ravicha2.github.io/openapi.json>
- API reference: <https://ravicha2.github.io/docs/>
- Sitemap: <https://ravicha2.github.io/sitemap.xml>